@unoverse-platform/studio 0.1.97 → 0.1.98

package/vendor/base/src/lint/objects/rules.mjs

@@ -0,0 +1,446 @@
+/**
+ * THE RULES an object or a pipeline file answers to, as PURE FUNCTIONS: a parsed document
+ * in, findings out. No filesystem, no schema, no dependency.
+ *
+ * ONE SPELLING OF EVERY RULE (docs/unoverse/data/objects/README.md 9a, 2026-09-10). The loaders
+ * in definitions/registry (objects.ts, pipelines.ts) used to refuse a wrong file by
+ * throwing their own sentence, and the linter would have said the same thing in other
+ * words. Now the loaders call these and throw the first finding; the linter reports every
+ * finding. The engine at boot and the editor at the keystroke say the same sentence about
+ * the same mistake.
+ *
+ * A finding is `{ file, msg }` where `file` is the folder-relative name of the file the
+ * mistake is in (`deal.yaml`, `props.yaml`, `api/service.yaml`, `pipeline.yaml`), so a
+ * caller that knows the folder can point at the line's file, and a caller that does not
+ * (the loader's thrown error) still names it. `refuses: true` marks the findings a LOADER
+ * cannot read past: the grammar itself (the type word, the name, the shape of calls and
+ * make). The rest (a missing face, a brief with no input, an unknown node) is the linter's
+ * to report and the engine's to tolerate at boot: a lint error blocks a publish, never a
+ * running universe.
+ */
+
+export const KEBAB = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const REF_OR_EXPR = /[{}]|^\s*return\b/;
+
+/** The twelve elements of the vocabulary (docs/unoverse/data/objects/elements/): what an object IS. */
+export const ELEMENTS = new Set(["purpose", "story", "content", "capability", "process", "asset", "task", "journey", "channel", "organisation", "people", "product", "brand", "document"]);
+
+/** The face every object and pipeline carries, as a node's node.yaml does. */
+export const FACE_KEYS = ["title", "description", "whenToUse", "category", "version"];
+
+/** The prop grammar of UNOVERSE_AUTHORING 3b plus the object's one word, `from` (README 4c). */
+export const PROP_KEYS = new Set(["type", "input", "description", "from", "hydrate", "enum", "oneOf", "minLength", "maxLength", "minItems", "maxItems", "items", "reuse"]);
+export const LIMIT_KEYS = ["minLength", "maxLength", "minItems", "maxItems"];
+
+/** Words that left the object grammar and must not come back (README 11.7, 12.3, 12.4). */
+const DROPPED_ENVELOPE_KEYS = {
+  lifecycle: "an object has functions in api/service.yaml, never a lifecycle (README 11.7)",
+  credentials: "a credential is never passed; the node a call names declares its type and the org's one credential of that type is found (README 12.4)",
+  allowedHosts: "an object names no host; the node a call names carries its hosts (README 12.3)",
+  cardinality: "how many one source makes is the pipeline's: each entry of its make says cardinality (one or many), not the object (docs/unoverse/data/pipelines/README.md, layer 1)",
+  manifest: "the envelope IS the manifest: title, description, whenToUse, category, version sit here (README 4a)",
+};
+
+const isRecord = (x) => !!x && typeof x === "object" && !Array.isArray(x);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// OBJECTS
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The envelope of object `name` (its `<name>.yaml`), before `extends` is composed.
+ * `file` is the envelope's file name, for the findings.
+ */
+export function envelopeFindings(name, envelope, file = `${name}.yaml`) {
+  const out = [];
+  const say = (msg) => out.push({ file, msg });
+  const refuse = (msg) => out.push({ file, msg, refuses: true });
+  if (!isRecord(envelope)) return [{ file, msg: `object ${name}: the envelope must be a record`, refuses: true }];
+  if (envelope.type !== "object") refuse(`object ${name}: envelope must declare type: object`);
+  if (envelope.name !== name) refuse(`object ${name}: name must equal the folder`);
+  if (!KEBAB.test(name)) say(`object ${name}: the name is kebab-case: it is the row's object_type and the folder's name`);
+  for (const k of FACE_KEYS) if (typeof envelope[k] !== "string" || !envelope[k].trim()) say(`object ${name}: the face needs "${k}": what this is and when an Agent reaches for it, as a node's node.yaml (README 4a)`);
+  if (envelope.element != null && (typeof envelope.element !== "string" || !ELEMENTS.has(envelope.element))) say(`object ${name}: element "${envelope.element}" is not one of the twelve elements (${[...ELEMENTS].join(", ")}). It says what the object IS, in the vocabulary's own word (README 4a)`);
+  if (envelope.icon != null && (typeof envelope.icon !== "string" || !KEBAB.test(envelope.icon))) say(`object ${name}: icon "${envelope.icon}" is not a lucide icon name in kebab-case (file-text)`);
+  if (envelope.storedAs != null && !/^[a-z_]+$/.test(String(envelope.storedAs))) say(`object ${name}: storedAs is one word, the stored object_type, not "${envelope.storedAs}"`);
+  if (envelope.extends != null && typeof envelope.extends !== "string") refuse(`object ${name}: extends names an object by name`);
+  else if (envelope.extends != null && !KEBAB.test(envelope.extends)) say(`object ${name}: extends names an object by its kebab-case name, not "${envelope.extends}"`);
+  if (envelope.embed != null && (!Array.isArray(envelope.embed) || !envelope.embed.length || envelope.embed.some((f) => typeof f !== "string"))) refuse(`object ${name}: embed is a list of field names`);
+  // ONE KEY, OR SEVERAL IN ORDER (README 4a): a flat list of fields, or a list of such lists.
+  if (envelope.uniqueBy != null) {
+    const u = envelope.uniqueBy;
+    const flat = Array.isArray(u) && u.length > 0 && u.every((f) => typeof f === "string");
+    const ordered = Array.isArray(u) && u.length > 0 && u.every((k) => Array.isArray(k) && k.length > 0 && k.every((f) => typeof f === "string"));
+    if (!flat && !ordered) refuse(`object ${name}: uniqueBy is a list of field names (one key), or a list of such lists (several keys, tried in order)`);
+  }
+  if (envelope.search != null && envelope.search !== "all" && (!Array.isArray(envelope.search) || envelope.search.some((f) => typeof f !== "string"))) refuse(`object ${name}: search is a list of field names, or "all"`);
+  // NEVER A ROW (README 7): an object with no embed has no place on the map, so it can
+  // have no identity to match on and nothing a search hit could carry.
+  if (envelope.embed == null) {
+    if (envelope.uniqueBy != null) say(`object ${name}: declares uniqueBy but no embed; an object with no embed is never positioned, and a part's identity is the row it is part of (README 7)`);
+    if (envelope.search != null) say(`object ${name}: declares search but no embed; an object with no embed is never searched: a part is walked to (README 7)`);
+  } else if (Array.isArray(envelope.search) && envelope.search[0] !== "universal_id") say(`object ${name}: search lists universal_id first; a search hit is addressed by it (README 9a)`);
+  for (const [k, why] of Object.entries(DROPPED_ENVELOPE_KEYS)) if (k in envelope) say(`object ${name}: "${k}" is not a word here: ${why}`);
+  // ITS LINES (relationships-and-labels.md): by name, each a type, the fields that group its
+  // rows, the field that orders them, and when a row draws it.
+  if (envelope.links != null) {
+    if (!isRecord(envelope.links)) refuse(`object ${name}: links is a record of lines by name`);
+    else for (const [ln, l] of Object.entries(envelope.links)) {
+      if (!isRecord(l)) { refuse(`object ${name}: link ${ln} is a record: type, between, order, when; or type, to, match`); continue; }
+      if (!["link", "flow", "tree"].includes(l.type)) refuse(`object ${name}: link ${ln}: type is link, flow or tree, not "${l.type}"`);
+      if (l.to != null || l.match != null) {
+        // A LINE TO ANOTHER OBJECT (relationships-and-labels.md): the object it points at, and one
+        // pair of fields: this row's naming that row's.
+        if (typeof l.to !== "string" || !KEBAB.test(l.to)) refuse(`object ${name}: link ${ln}: to names the object the line points at, by its kebab-case name`);
+        const pairs = isRecord(l.match) ? Object.entries(l.match) : [];
+        if (pairs.length !== 1 || pairs.some(([a, b]) => typeof a !== "string" || typeof b !== "string" || !a || !b)) refuse(`object ${name}: link ${ln}: match is one pair, this row's field naming that row's ({ manager: legalName })`);
+        if (l.between != null || l.order != null) refuse(`object ${name}: link ${ln}: a line to another object says to and match, never between or order`);
+        if (l.alike != null && (!Array.isArray(l.alike) || l.alike.some((f) => typeof f !== "string" || !pairs.some(([a]) => a === f)))) refuse(`object ${name}: link ${ln}: alike lists this row's match field whose value may name one thing several ways`);
+        for (const k of Object.keys(l)) if (!["type", "to", "match", "when", "alike"].includes(k)) say(`object ${name}: link ${ln}: "${k}" is not a word here`);
+        continue;
+      }
+      if (!Array.isArray(l.between) || !l.between.length || l.between.some((f) => typeof f !== "string")) refuse(`object ${name}: link ${ln}: between is a list of the fields whose equal values make one line of rows`);
+      if (typeof l.order !== "string" || !l.order) refuse(`object ${name}: link ${ln}: order names the field its rows are put in order by`);
+      if (l.when != null && typeof l.when !== "string") refuse(`object ${name}: link ${ln}: when is an expression over the row`);
+      if (l.alike != null && (!Array.isArray(l.alike) || l.alike.some((f) => typeof f !== "string" || !(l.between ?? []).includes(f)))) refuse(`object ${name}: link ${ln}: alike lists fields of between whose values may name one thing several ways`);
+      for (const k of Object.keys(l)) if (!["type", "between", "order", "when", "alike"].includes(k)) say(`object ${name}: link ${ln}: "${k}" is not a word here`);
+    }
+  }
+  return out;
+}
+
+/**
+ * The props an object declares ITSELF (props.yaml, or the envelope's inline record), with
+ * the parent's composed props when the object extends one. Every own prop is a brief with
+ * an explicit input; an inherited field is re-briefed with description alone.
+ */
+export function propsFindings(name, ownProps, parentProps = null, base = null, file = "props.yaml") {
+  const out = [];
+  const say = (msg) => out.push({ file, msg });
+  if (ownProps == null) return out;
+  if (!isRecord(ownProps)) return [{ file, msg: `object ${name}: props is a record, one prop per field`, refuses: true }];
+  for (const [k, raw] of Object.entries(ownProps)) {
+    if (!isRecord(raw)) {
+      out.push({ file, msg: `object ${name}: prop "${k}" must be a record: a brief with a type and an input`, refuses: true });
+      continue;
+    }
+    const inherited = parentProps && k in parentProps;
+    if (inherited) {
+      // RE-BRIEF (README 5): an object may say its own brief for a field it inherits, and
+      // nothing else about it. A product's title is the offering's name, not the need's outcome.
+      const extra = Object.keys(raw).filter((key) => key !== "description");
+      if (extra.length) out.push({ file, refuses: true, msg: `object ${name}: redeclares "${k}", which its base ${base} already declares; an inherited field may only be re-briefed (description), not ${extra.join(", ")}` });
+      if (typeof raw.description !== "string" || !raw.description.trim()) say(`object ${name}: prop "${k}" re-briefs an inherited field, so it carries a description`);
+      continue;
+    }
+    for (const key of Object.keys(raw)) if (!PROP_KEYS.has(key)) say(`object ${name}: prop "${k}" carries "${key}", which is not a word of the prop grammar (${[...PROP_KEYS].join(", ")}); an object is a kind, never an instance, so no default or preview (README 4c)`);
+    if (typeof raw.description !== "string" || !raw.description.trim()) say(`object ${name}: prop "${k}" carries no description. The prop IS the brief: the description is the whole instruction for the field (README 4c)`);
+    if (typeof raw.input !== "boolean") say(`object ${name}: prop "${k}" says no input. Every own prop says who writes it: input: true, the model from the source; input: false, the engine or a function (README 4c)`);
+    for (const lim of LIMIT_KEYS) if (raw[lim] != null && !Number.isInteger(raw[lim])) say(`object ${name}: prop "${k}": ${lim} is a number, not "${raw[lim]}"`);
+    // A CHOICE LISTS ITS OPTIONS (README 4c, 2026-09-13): each a const, a title and a description; never with enum.
+    if (raw.oneOf != null) {
+      if (!Array.isArray(raw.oneOf) || !raw.oneOf.length || raw.oneOf.some((o) => !isRecord(o) || typeof o.const !== "string" || !o.const.trim())) say(`object ${name}: prop "${k}": oneOf is a list of options, each with a const (the stored word), a title and a description`);
+      else if (raw.oneOf.some((o) => typeof o.description !== "string" || !o.description.trim())) say(`object ${name}: prop "${k}": every option of oneOf says its description, how the model tells it apart`);
+      if (raw.enum != null) say(`object ${name}: prop "${k}" says both enum and oneOf; one or the other`);
+    }
+    if (raw.type === "array" && !isRecord(raw.items)) say(`object ${name}: prop "${k}" is an array and carries no items: an array says the shape of one element, in the same grammar one level down (README 4c)`);
+  }
+  return out;
+}
+
+/** `from: <function>.<return>` on a prop, against the object's functions: `make` (api/make.yaml) and api/service.yaml's (README 4b). */
+export function fromFindings(name, prop, from, service, file = "props.yaml") {
+  const out = [];
+  const say = (msg) => out.push({ file, msg, refuses: true });
+  const [fn, ret, ...rest] = String(from).split(".");
+  if (!fn || !ret || rest.length) {
+    say(`object ${name}: prop "${prop}" from "${from}" must read <function>.<return>`);
+    return out;
+  }
+  const api = isRecord(service) ? Object.keys(service) : [];
+  if (!api.includes(fn)) {
+    say(`object ${name}: prop "${prop}" is from "${fn}", which the object does not declare (make is api/make.yaml, the rest api/service.yaml)`);
+    return out;
+  }
+  const returns = service[fn]?.returns;
+  if (returns && typeof returns === "object" && !(ret in returns)) say(`object ${name}: prop "${prop}" is from "${from}", but ${fn} returns no "${ret}"`);
+  return out;
+}
+
+/**
+ * One function of api/service.yaml (README 4b): `calls` in the node's grammar, `returns`.
+ * The list's word is the node's: never `steps`. A call needs a name and a node; names are
+ * unique; `for` and `when` are strings.
+ */
+export function functionFindings(name, fn, raw, file = "api/service.yaml") {
+  const out = [];
+  const say = (msg, level) => out.push(level ? { file, msg, level } : { file, msg, refuses: true });
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) return [{ file, msg: `object ${name}: function ${fn} must be a record with calls and returns`, refuses: true }];
+  if ("steps" in raw) say(`object ${name}: function ${fn} says steps; the word is calls, as in a node's api/run.yaml (a step is a node on a canvas)`);
+  // THE FILE IS THE SWITCH (README 4b, 2026-09-14): api/service.yaml may be called from outside,
+  // api/make.yaml is private. Nothing inside a function says who may call it.
+  if ("tool" in raw) say(`object ${name}: function ${fn} says tool; the file is the switch: api/service.yaml may be called from outside, api/make.yaml is private (README 4b)`);
+  // ITS INPUTS (README 4b): a JSON schema of what a caller passes, the word an Agent's tools use.
+  if ("input" in raw && !(isRecord(raw.input) && raw.input.type === "object" && isRecord(raw.input.properties))) say(`object ${name}: function ${fn}: input is a JSON schema of its arguments: type: object, with properties`);
+  const list = raw.calls == null ? [] : raw.calls;
+  if (!Array.isArray(list)) {
+    say(`object ${name}: function ${fn}: calls must be a list`);
+    return out;
+  }
+  const names = new Set();
+  list.forEach((c, i) => {
+    if (c == null || typeof c !== "object" || typeof c.name !== "string" || !c.name) {
+      say(`object ${name}: function ${fn}: call ${i} needs a name`);
+      return;
+    }
+    if (names.has(c.name)) say(`object ${name}: function ${fn}: two calls named "${c.name}"`);
+    names.add(c.name);
+    if (typeof c.node !== "string") say(`object ${name}: function ${fn}: call "${c.name}" names no node, the only way an object touches the world (README 12.5)`);
+    if (c.for != null && typeof c.for !== "string") say(`object ${name}: function ${fn}: call "${c.name}": for must be a reference to a list`);
+    if (c.when != null && typeof c.when !== "string") say(`object ${name}: function ${fn}: call "${c.name}": when must be an expression`);
+    for (const k of ["credentials", "allowedHosts", "credential"]) if (k in c) say(`object ${name}: function ${fn}: call "${c.name}" carries "${k}"; a credential is never passed, the node declares its type (README 12.4)`);
+  });
+  return out;
+}
+
+/**
+ * The service file whole (README 4b): every function a record; `getDetail` the one fixed
+ * name; every call's node one the tier can see, when the tier is visible.
+ */
+export function serviceFindings(name, service, nodeTypes = null, file = "api/service.yaml") {
+  const out = [];
+  if (service == null) return out;
+  if (!isRecord(service)) return [{ file, msg: `object ${name}: api/service.yaml is a record of functions by name (getDetail, searchDetail)` }];
+  for (const [fn, raw] of Object.entries(service)) {
+    out.push(...functionFindings(name, fn, raw, file));
+    if (!Array.isArray(raw?.calls)) continue;
+    for (const c of raw.calls) {
+      if (!c || typeof c.node !== "string") continue;
+      if (nodeTypes && !nodeTypes.has(c.node)) out.push({ file, msg: `object ${name}: function ${fn}: call "${c.name}" names node "${c.node}", which neither the marketplace nor this org holds. A call runs a node the org has; the node's folder is design/<tier>/nodes/<package>/nodes/${c.node}/` });
+    }
+  }
+  return out;
+}
+
+/**
+ * api/make.yaml (README 4b, 2026-09-14): the private make function, one function with no name
+ * inside it, run only by the pipeline. The public file never declares it: `service` is the
+ * api/service.yaml record, so a make function put there is refused.
+ */
+export function makeFindings(name, make, service, nodeTypes = null, file = "api/make.yaml") {
+  const out = [];
+  if (isRecord(service)) for (const reserved of ["make", "makeDetail"]) if (reserved in service) out.push({ file: "api/service.yaml", msg: `object ${name}: api/service.yaml declares ${reserved}; the make function is private: it lives in api/make.yaml, one function with no name inside it (README 4b)`, refuses: true });
+  if (make == null) return out;
+  if (!isRecord(make)) return [...out, { file, msg: `object ${name}: api/make.yaml is one function: description, calls and returns`, refuses: true }];
+  if ("makeDetail" in make) out.push({ file, msg: `object ${name}: api/make.yaml names makeDetail; the file is the function, so its description, calls and returns sit at the top (README 4b)`, refuses: true });
+  out.push(...functionFindings(name, "make", make, file));
+  if (nodeTypes && Array.isArray(make.calls)) for (const c of make.calls) if (c && typeof c.node === "string" && !nodeTypes.has(c.node)) out.push({ file, msg: `object ${name}: make: call "${c.name}" names node "${c.node}", which neither the marketplace nor this org holds. A call runs a node the org has; the node's folder is design/<tier>/nodes/<package>/nodes/${c.node}/` });
+  return out;
+}
+
+/**
+ * The row keys against the fields, once `extends` is composed: every field named in
+ * uniqueBy, embed and search is a prop. `props` is the composed record.
+ */
+export function rowKeyFindings(name, envelope, props, file = `${name}.yaml`) {
+  const out = [];
+  if (!isRecord(envelope) || !isRecord(props)) return out;
+  const known = new Set([...Object.keys(props), "universal_id", "object_type", "source_url", "source_id", "app", "meta"]);
+  for (const key of ["uniqueBy", "embed", "search"]) {
+    const list = envelope[key];
+    if (!Array.isArray(list)) continue;
+    for (const f of list.flat()) if (typeof f === "string" && !known.has(f) && !known.has(camel(f))) out.push({ file, msg: `object ${name}: ${key} names "${f}", which is not a prop of this object or its base. A row key is a field (README 9a)` });
+  }
+  return out;
+}
+
+const camel = (s) => s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+
+/** test.yaml: the fakes name the function's calls; every expect is an expression. */
+export function objectTestFindings(name, test, service, file = "test.yaml") {
+  const out = [];
+  // A TEST IS FOR A FUNCTION THE ENGINE RUNS: an object whose functions call no node (or
+  // has none) has nothing to fake and nothing to return; its row is the object, and the
+  // model's work is never faked. Only an object with a call to fake is asked for a test.
+  const callsNodes = isRecord(service) && Object.values(service).some((f) => Array.isArray(f?.calls) && f.calls.some((c) => typeof c?.node === "string"));
+  if (test == null) return callsNodes ? [{ file, level: "warn", msg: `object ${name}: no test.yaml, yet its functions call nodes. An object nobody can run is an object nobody can trust (README 12.2)` }] : [];
+  const td = test?.testData;
+  if (!isRecord(td)) return [{ file, msg: `object ${name}: test.yaml carries testData: a row, the fakes by call name, the expects` }];
+  const handler = td.row?.content?.handler;
+  const fnRaw = handler && isRecord(service) ? service[handler] : null;
+  if (handler && isRecord(service) && !fnRaw) out.push({ file, msg: `object ${name}: the test row's handler "${handler}" is no function of the object` });
+  const callNames = new Set(Array.isArray(fnRaw?.calls) ? fnRaw.calls.map((c) => c?.name) : []);
+  if (isRecord(td.fake) && fnRaw) for (const k of Object.keys(td.fake)) if (!callNames.has(k)) out.push({ file, msg: `object ${name}: test fakes "${k}", which is no call of ${handler}. A fake stands in for one call, by its name` });
+  if (isRecord(td.expect)) for (const [k, v] of Object.entries(td.expect)) if (typeof v !== "string" || !v.trim()) out.push({ file, msg: `object ${name}: expect "${k}" is an expression over output` });
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// PIPELINES
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** What an entry under `each` says about its row; every other key is an object that row becomes. */
+export const PIPELINE_READ_KEYS = new Set(["each", "sourceUrl", "sourceId", "content"]);
+/** Words the 2026-09-15 shape dropped (docs/unoverse/data/pipelines/history.md), refused with a pointer. */
+const DROPPED_MAKE_KEYS = ["partsOf", "by", "under", "when", "from", "any", "index"];
+
+/** What an object may say: under `each`, how many and what it holds; made once per pack, how many and from which rows. */
+const ITEM_OBJECT_KEYS = new Set(["cardinality", "any", "parts", "where"]);
+const FIELD = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * pipeline.yaml whole (docs/unoverse/data/pipelines/README.md layer 1): the face, `collect` as node steps
+ * in order, `make` a list of reads, each naming the objects it makes. `row`, `yields` and `from` are gone.
+ * Returns findings in the order the loader used to throw them.
+ */
+export function pipelineFindings(name, file, fileName = "pipeline.yaml") {
+  const out = [];
+  const say = (msg) => out.push({ file: fileName, msg });
+  const refuse = (msg) => out.push({ file: fileName, msg, refuses: true });
+  if (!isRecord(file)) return [{ file: fileName, msg: `pipeline ${name}: pipeline.yaml must be a record`, refuses: true }];
+  if (file.type !== "pipeline") refuse(`pipeline ${name}: pipeline.yaml must declare type: pipeline`);
+  if (file.name !== name) refuse(`pipeline ${name}: name must equal the folder`);
+  if (!KEBAB.test(name)) say(`pipeline ${name}: the name is kebab-case: it is the folder's name and the connector's`);
+  for (const k of FACE_KEYS) if (typeof file[k] !== "string" || !file[k].trim()) say(`pipeline ${name}: the face needs "${k}", as a node's node.yaml (docs/unoverse/data/pipelines/README.md layer 1)`);
+  if (typeof file.color !== "string" || !/^#[0-9a-fA-F]{6}$/.test(file.color)) say(`pipeline ${name}: color is the accent on the canvas and the Import screen, a hex colour`);
+  if (typeof file.logoUrl !== "string" || !file.logoUrl.trim()) say(`pipeline ${name}: logoUrl is the mark on the canvas and the Import screen`);
+  for (const k of ["credentials", "allowedHosts", "url", "method"]) if (k in file) say(`pipeline ${name}: "${k}" is not a word here; nodes are the only way a pipeline touches the world (docs/unoverse/data/pipelines/README.md, decided 2026-09-09 5)`);
+
+  const stepNames = new Set();
+  if (!Array.isArray(file.collect) || !file.collect.length) refuse(`pipeline ${name}: collect must list at least one step`);
+  else
+    file.collect.forEach((s, i) => {
+      if (!isRecord(s) || typeof s.name !== "string" || typeof s.node !== "string") {
+        refuse(`pipeline ${name}: collect step ${i} needs a name and a node`);
+        return;
+      }
+      if (stepNames.has(s.name)) refuse(`pipeline ${name}: two collect steps named "${s.name}"`);
+      // A step reads only what came before it.
+      for (const ref of collectRefs(s.config)) if (!stepNames.has(ref)) say(`pipeline ${name}: collect step "${s.name}" reads collect.${ref}, which is not an earlier step`);
+      stepNames.add(s.name);
+    });
+
+  if ("row" in file || "yields" in file) refuse(`pipeline ${name}: row and yields are gone; a pipeline is collect and make (docs/unoverse/data/pipelines/README.md layer 1)`);
+  // `make` LISTS WHAT IS MADE, IN ORDER (docs/unoverse/data/pipelines/README.md, `make`, 2026-09-15;
+  // a-document-decides.md, 2026-09-20): every entry is under `each`, and makes objects from each
+  // item's read, with their parts, their index and the `where` that says which reads make them.
+  // There is no entry made once per folder: a folder is where a file was found, never what it is.
+  const see = `docs/unoverse/data/pipelines/README.md, make`;
+  if (isRecord(file.make)) refuse(`pipeline ${name}: make is a list: "- each: <list>" and the objects each item's read becomes (${see})`);
+  else if (!Array.isArray(file.make) || !file.make.length) refuse(`pipeline ${name}: make must list at least one object`);
+  else {
+    const made = [];
+    file.make.forEach((raw, i) => {
+      const at = `make[${i}]`;
+      if (!isRecord(raw)) {
+        refuse(`pipeline ${name}: ${at} must be a record`);
+        return;
+      }
+      for (const k of DROPPED_MAKE_KEYS) if (k in raw) refuse(`pipeline ${name}: ${at}: ${k} is not a word here since 2026-09-15; parts and the index sit under their object, and an object made once per pack says where: (${see})`);
+      const hasEach = "each" in raw;
+      const objects = Object.keys(raw).filter((k) => !PIPELINE_READ_KEYS.has(k) && !DROPPED_MAKE_KEYS.includes(k));
+      if (!objects.length) refuse(`pipeline ${name}: ${at} names no object it makes`);
+      if (hasEach) {
+        const list = typeof raw.each === "string" ? raw.each.trim() : "";
+        if (!list || !REF_OR_EXPR.test(list)) refuse(`pipeline ${name}: ${at}: each is a list over collect, {{ collect.<step>.<list> }}`);
+        if ("content" in raw && !isRecord(raw.content)) refuse(`pipeline ${name}: ${at}: content is what the row carries instead of the item as listed, a record`);
+        for (const k of ["sourceUrl", "sourceId"]) if (k in raw && (typeof raw[k] !== "string" || !raw[k].trim())) refuse(`pipeline ${name}: ${at}: ${k} is an expression over item`);
+        for (const ref of collectRefs([raw.each, raw.sourceUrl, raw.sourceId, raw.content])) if (!stepNames.has(ref)) say(`pipeline ${name}: ${at} reads collect.${ref}, which is no collect step`);
+      } else {
+        // A FOLDER IS NOT A THING (docs/unoverse/data/pipelines/a-document-decides.md, 2026-09-20).
+        // An entry with no `each` was made once per folder, and its row's identity was the folder's
+        // address, so two funds named in one folder were one row and a figure could name a fund
+        // with no row to belong to. What an object IS comes from the read that states it.
+        refuse(`pipeline ${name}: ${at}: every entry reads a list; an object made once per folder is gone, say where: on the object beside each: (${see})`);
+      }
+      for (const o of objects) {
+        const spec = raw[o];
+        if (!isRecord(spec)) {
+          refuse(`pipeline ${name}: ${at}.${o}: an object is its name with a record ({ cardinality: one })`);
+          continue;
+        }
+        if (made.includes(o)) refuse(`pipeline ${name}: ${at}.${o} is made above already; one entry makes an object`);
+        const allowed = ITEM_OBJECT_KEYS;
+        for (const k of Object.keys(spec)) if (!allowed.has(k)) refuse(`pipeline ${name}: ${at}.${o}: "${k}" is not a word here; an object says cardinality, any, parts and where (${see})`);
+        // HOW MANY IS SAID by every object the model writes (owner, 2026-09-13).
+        if (spec.cardinality !== "one" && spec.cardinality !== "many") say(`pipeline ${name}: ${at}.${o} says cardinality: one or many, how many of it one row makes (${see})`);
+        if ("any" in spec && spec.any !== true) refuse(`pipeline ${name}: ${at}.${o}: any: true is its only value, the item MAY be one`);
+        if ("parts" in spec) {
+          if (!isRecord(spec.parts) || !Object.keys(spec.parts).length) refuse(`pipeline ${name}: ${at}.${o}: parts names each part and the list of the read it comes from: table: "{{ detail.tables }}"`);
+          else for (const [part, from] of Object.entries(spec.parts)) {
+            if (typeof from !== "string" || !REF_OR_EXPR.test(from.trim())) refuse(`pipeline ${name}: ${at}.${o}.parts.${part}: a list of what ${o}'s read returned, {{ detail.<list> }}`);
+            if (made.includes(part)) refuse(`pipeline ${name}: ${at}.${o}.parts.${part} is made above already`);
+            made.push(part);
+          }
+        }
+        if ("where" in spec) {
+          if (!isRecord(spec.where) || !Object.keys(spec.where).length) refuse(`pipeline ${name}: ${at}.${o}: where lists, per field, the values the READ must hold for this item to make it: reportType: [offering-memorandum]`);
+          else for (const [field, values] of Object.entries(spec.where))
+            if (!FIELD.test(field) || !Array.isArray(values) || !values.length || values.some((v) => typeof v !== "string" && typeof v !== "number"))
+              refuse(`pipeline ${name}: ${at}.${o}.where.${field}: a field's name and the list of values it may hold`);
+        }
+        made.push(o);
+      }
+    });
+  }
+  return out;
+}
+
+/** Every `collect.<step>` a value reads, through `{{ }}` and return expressions alike. */
+export function collectRefs(value) {
+  const out = new Set();
+  const walk = (v) => {
+    if (typeof v === "string") for (const m of v.matchAll(/\bcollect\.([A-Za-z_][A-Za-z0-9_]*)/g)) out.add(m[1]);
+    else if (Array.isArray(v)) v.forEach(walk);
+    else if (isRecord(v)) Object.values(v).forEach(walk);
+  };
+  walk(value);
+  return out;
+}
+
+/** Every `config.<key>` a value reads. */
+export function configRefs(value) {
+  const out = new Set();
+  const walk = (v) => {
+    if (typeof v === "string") for (const m of v.matchAll(/\bconfig\.([A-Za-z_][A-Za-z0-9_]*)/g)) out.add(m[1]);
+    else if (Array.isArray(v)) v.forEach(walk);
+    else if (isRecord(v)) Object.values(v).forEach(walk);
+  };
+  walk(value);
+  return out;
+}
+
+/**
+ * The cross-file rules of a pipeline folder: every collect node one the tier can see, every
+ * make key an object the tier can see, every config.<key> a property of config.yaml, the
+ * test's fakes named for collect steps.
+ */
+export function pipelineFolderFindings(name, { file, config, test }, { nodeTypes = null, objectNames = null } = {}) {
+  const out = [];
+  if (!isRecord(file)) return out;
+  const steps = Array.isArray(file.collect) ? file.collect.filter(isRecord) : [];
+  if (nodeTypes) for (const s of steps) if (typeof s.node === "string" && !nodeTypes.has(s.node)) out.push({ file: "pipeline.yaml", msg: `pipeline ${name}: collect step "${s.name}" names node "${s.node}", which neither the marketplace nor this org holds. A step runs a node the org has` });
+  if (objectNames && isRecord(file.make)) for (const object of Object.keys(file.make)) if (!objectNames.has(object)) out.push({ file: "pipeline.yaml", msg: `pipeline ${name}: make.${object} names an object neither the marketplace nor this org holds. What a pipeline makes is an object folder: design/<tier>/objects/${object}/` });
+  const props = isRecord(config?.configSchema?.properties) ? new Set(Object.keys(config.configSchema.properties)) : null;
+  const refs = configRefs(file);
+  if (refs.size && !config) out.push({ file: "config.yaml", msg: `pipeline ${name}: reads config.${[...refs].join(", config.")} but has no config.yaml. What a person sets to run it is the Import form, a node's configSchema` });
+  else if (props) for (const r of refs) if (!props.has(r)) out.push({ file: "config.yaml", msg: `pipeline ${name}: reads config.${r}, which config.yaml does not declare` });
+  if (test == null) out.push({ file: "test.yaml", level: "warn", msg: `pipeline ${name}: no test.yaml. A pipeline nobody can run is a pipeline nobody can trust` });
+  else if (isRecord(test?.testData?.fake)) {
+    const stepNames = new Set(steps.map((s) => s.name));
+    for (const k of Object.keys(test.testData.fake)) if (!stepNames.has(k)) out.push({ file: "test.yaml", msg: `pipeline ${name}: test fakes "${k}", which is no collect step. A fake stands in for one step, by its name` });
+  }
+  return out;
+}
+
+/** The first error's message. */
+export function firstError(findings) {
+  const f = findings.find((x) => !x.level || x.level === "error");
+  return f ? f.msg : null;
+}
+
+/** The first finding a loader cannot read past, for a loader that refuses a file by throwing; null when the file loads. */
+export function firstRefusal(findings) {
+  const f = findings.find((x) => x.refuses);
+  return f ? f.msg : null;
+}

package/vendor/base/src/lint/prompts/index.d.mts

@@ -0,0 +1,34 @@
+/**
+ * Types for the prompts linter (Agent skills and prompt blocks), which is plain JavaScript.
+ *
+ * Same arrangement as ../objects/index.d.mts: the linter stays .mjs so the CLIs run it
+ * under bare node, and TypeScript consumers (the publish gate, Studio) get a shape.
+ */
+
+export interface Finding {
+  level: "error" | "warn" | "hint";
+  file: string;
+  line?: number;
+  msg: string;
+}
+
+export interface PromptsResult {
+  problems: Finding[];
+  skillCount: number;
+  blockCount: number;
+  designRoot: string;
+}
+
+export interface LintPromptsOptions {
+  /** Absolute path -> text that stands in for what is on disk (an unsaved editor). */
+  overlay?: Record<string, string>;
+}
+
+/** Lint every skill and prompt block under `designRoot`, every tier. Prints nothing, throws nothing for a lint failure. */
+export function lintPrompts(designRoot: string, options?: LintPromptsOptions): PromptsResult;
+
+/** Frontmatter and body of a markdown file, the way the run-time loaders split it. */
+export function splitFrontmatter(text: string): { data: Record<string, unknown> | null; body: string; error: string | null; line: number };
+
+/** True when anything would fail a build. */
+export function hasErrors(result: PromptsResult): boolean;