unoverse 0.1.205 → 0.1.207

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/lib/lint.mjs +15 -1
  2. package/operator/ansible/playbooks/install.yml +1 -1
  3. package/operator/docker-compose.yml +32 -4
  4. package/operator/lib/check.sh +2 -2
  5. package/operator/lib/db-verify.sh +22 -4
  6. package/package.json +1 -1
  7. package/vendor/base/items/collect.js +30 -26
  8. package/vendor/base/items/publish.js +30 -6
  9. package/vendor/base/lint/context.mjs +17 -0
  10. package/vendor/base/lint/design/file.mjs +199 -2
  11. package/vendor/base/lint/design/index.mjs +66 -73
  12. package/vendor/base/lint/design/vocabulary.mjs +5 -2
  13. package/vendor/base/lint/design/walk.mjs +14 -4
  14. package/vendor/base/lint/nodes/_schema/_defs.schema.json +1 -1
  15. package/vendor/base/lint/nodes/_schema/api.schema.json +60 -1
  16. package/vendor/base/lint/nodes/_schema/audio.schema.json +27 -4
  17. package/vendor/base/lint/nodes/_schema/config.schema.json +3 -2
  18. package/vendor/base/lint/nodes/_schema/credential.schema.json +88 -4
  19. package/vendor/base/lint/nodes/_schema/interface.schema.json +57 -0
  20. package/vendor/base/lint/nodes/_schema/node.schema.json +59 -12
  21. package/vendor/base/lint/nodes/_schema/package.schema.json +4 -0
  22. package/vendor/base/lint/nodes/blocks.mjs +6 -2
  23. package/vendor/base/lint/nodes/index.mjs +5 -0
  24. package/vendor/base/lint/nodes/node.mjs +157 -7
  25. package/vendor/base/lint/objects/_schema/objects/dataset.schema.json +84 -0
  26. package/vendor/base/lint/objects/_schema/objects/make.schema.json +95 -0
  27. package/vendor/base/lint/objects/_schema/objects/object.schema.json +266 -0
  28. package/vendor/base/lint/objects/_schema/objects/props.schema.json +243 -0
  29. package/vendor/base/lint/objects/_schema/objects/service.schema.json +109 -0
  30. package/vendor/base/lint/objects/_schema/objects/test.schema.json +76 -0
  31. package/vendor/base/lint/objects/_schema/pipelines/config.schema.json +6 -0
  32. package/vendor/base/lint/objects/_schema/pipelines/interface.schema.json +6 -0
  33. package/vendor/base/lint/objects/_schema/pipelines/pipeline.schema.json +161 -0
  34. package/vendor/base/lint/objects/_schema/pipelines/test.schema.json +42 -0
  35. package/vendor/base/lint/objects/index.mjs +324 -0
  36. package/vendor/base/lint/objects/rules.mjs +446 -0
  37. package/vendor/base/lint/prompts/index.mjs +198 -0
@@ -67,7 +67,7 @@ export function lintDefinitions(designRoot, options = {}) {
67
67
  try {
68
68
  return (
69
69
  statSync(d).isDirectory() &&
70
- ["components", "atoms", "styles", "apps"].some((s) => existsSync(join(d, s)))
70
+ ["components", "atoms", "styles", "apps", "agents"].some((s) => existsSync(join(d, s)))
71
71
  );
72
72
  } catch {
73
73
  return false;
@@ -96,9 +96,7 @@ export function lintDefinitions(designRoot, options = {}) {
96
96
  const DS = (() => {
97
97
  const onDisk = join(DESIGN_ROOT, "marketplace");
98
98
  if (existsSync(onDisk)) return onDisk;
99
- const nodesHome = resolve(DESIGN_ROOT, "..", "nodes");
100
99
  for (const c of [
101
- join(nodesHome, "marketplace", "definitions"),
102
100
  join(resolve(DESIGN_ROOT, "..", "plugins"), "node_modules", "@unoverse-platform", "marketplace", "definitions"),
103
101
  ])
104
102
  if (existsSync(c)) return c;
@@ -190,6 +188,9 @@ const isAppPath = (f) => homeSegments(f).includes("apps");
190
188
  // carry no manifest and declare no state tree, the face being the filename (§9b rule 7).
191
189
  const isTemplatePath = (f) => homeSegments(f).includes("templates");
192
190
  const isTemplatePart = (f) => isTemplatePath(f) && homeSegments(f).includes("components");
191
+ // THE AGENT KIND (docs.unoverse.ai/design/tasks, 2026-09-06): one file under <org>/agents/,
192
+ // a workflow listed for the map. Not a UI tree, so the tree rules do not apply; its own check does.
193
+ const isAgentPath = (f) => homeSegments(f).includes("agents");
193
194
  // The DEFINITION ROOT folder for a file: a bare partial lives one level under it
194
195
  // (layouts/ states/ components/ blocks/); every `$include` resolves against it.
195
196
  const defRoot = (file) => {
@@ -597,7 +598,7 @@ const keyHomes = [
597
598
  [join(DS, "components"), true],
598
599
  ];
599
600
  for (const orgDir of orgDirs) {
600
- keyHomes.push([join(orgDir, "components"), true], [join(orgDir, "apps"), true]);
601
+ keyHomes.push([join(orgDir, "components"), true], [join(orgDir, "apps"), true], [join(orgDir, "agents"), false]);
601
602
  }
602
603
  for (const [dir, isDir] of keyHomes) {
603
604
  if (!existsSync(dir)) continue;
@@ -638,7 +639,9 @@ for (const [dir, isDir] of keyHomes) {
638
639
  // carries are ordinary components, so they were never exempt from anything.
639
640
  const homes = [{ dir: join(DS, "components") }, { dir: join(DS, "atoms") }, { dir: join(DS, "templates") }];
640
641
  for (const orgDir of orgDirs) {
641
- for (const sub of ["apps", "components", "templates"]) {
642
+ // `agents` (2026-09-06): a kind is linted; a home not enumerated is a home where every
643
+ // rule is off, silently.
644
+ for (const sub of ["apps", "components", "templates", "agents"]) {
642
645
  const d = join(orgDir, sub);
643
646
  if (existsSync(d) && statSync(d).isDirectory()) homes.push({ dir: d });
644
647
  }
@@ -701,64 +704,27 @@ for (const orgDir of orgDirs) {
701
704
  );
702
705
  }
703
706
 
704
- /**
705
- * ── the LATCH, on a state (docs/MCP_COMPLETE_GUIDE.md §The Component Latch) ──
706
- *
707
- * Declaring it makes whatever wears that face ADDRESSABLE: the pill goes up and the guest's
708
- * next sentences travel to that instance instead of opening a new answer. Every finding here
709
- * is something that produces a pill which looks fine and behaves wrongly, which is why they
710
- * are errors rather than warnings.
711
- *
712
- * Read from the ENVELOPE first and the manifest second, the same order the loader reads the
713
- * states tree in — a rule that judged only one home would pass whatever was authored in the
714
- * other.
715
- */
716
- const LATCH_KEYS = new Set(["title", "icon"]);
707
+ // ── `latch`, RETIRED (2026-09-07) ──
708
+ // The conversation is never "addressed at" a component: what is on screen is the server's
709
+ // fact and the model reads it. A leftover block is an intent nothing honours, so it errors.
717
710
  for (const orgDir of orgDirs) {
718
711
  const adir = join(orgDir, "apps");
719
712
  if (!(existsSync(adir) && statSync(adir).isDirectory())) continue;
720
713
  for (const e of readdirSync(adir)) {
721
714
  const folder = join(adir, e);
722
- let src, states;
723
715
  try {
724
716
  if (!statSync(folder).isDirectory()) continue;
725
- // The envelope (`<name>.yaml`) is the app tree's home; the manifest is the legacy one.
726
- const envelope = defPath(folder, e);
727
- const manifest = defPath(folder, "manifest");
728
- for (const p of [envelope, manifest]) {
717
+ for (const p of [defPath(folder, e), defPath(folder, "manifest")]) {
729
718
  if (!p || !existsSync(p)) continue;
730
- const s = readDef(p).states;
731
- if (s && typeof s === "object" && !Array.isArray(s)) {
732
- src = p;
733
- states = s;
734
- break;
735
- }
719
+ const states = readDef(p).states;
720
+ if (!states || typeof states !== "object" || Array.isArray(states)) continue;
721
+ for (const [sname, sentry] of Object.entries(states))
722
+ if (sentry && typeof sentry === "object" && !Array.isArray(sentry) && sentry.latch !== undefined)
723
+ report("error", p, `state "${sname}": "latch" is retired (2026-09-07). Delete the block — the model reads what is on screen; nothing addresses a component`);
736
724
  }
737
725
  } catch {
738
726
  continue; // a malformed envelope is reported elsewhere
739
727
  }
740
- if (!states) continue;
741
- for (const [sname, sentry] of Object.entries(states)) {
742
- const latch = sentry && typeof sentry === "object" && !Array.isArray(sentry) ? sentry.latch : undefined;
743
- if (latch === undefined) continue;
744
- if (typeof latch !== "object" || latch === null || Array.isArray(latch)) {
745
- report("error", src, `state "${sname}": "latch" must be a block ({ title, icon }), not ${Array.isArray(latch) ? "a list" : typeof latch}. Presence is what makes a state addressable, so a malformed one is an intent nothing can honour (docs/MCP_COMPLETE_GUIDE.md §The Component Latch)`);
746
- continue;
747
- }
748
- // The pill is the ONLY sign the guest has that their words are landing on this page
749
- // rather than the conversation. Unlabelled, it says nothing — and the compiler drops
750
- // a titleless block, so the state would silently stop being addressable.
751
- if (typeof latch.title !== "string" || !latch.title.trim())
752
- report("error", src, `state "${sname}": "latch" needs a "title" — it is what the pill reads, and the pill is the only thing telling the guest what they are addressing. Name the thing, not the verb ("Your Perfect Day", not "Edit the day")`);
753
- const extra = Object.keys(latch).filter((k) => !LATCH_KEYS.has(k));
754
- if (extra.length)
755
- report("error", src, `state "${sname}": "latch" has no key(s) ${extra.join(", ")}. The block is exactly ${[...LATCH_KEYS].join(", ")} — an invented key is silently ignored, so whatever it was meant to do never happens. The pill's colours belong to the design system's composer-bar, never to a state`);
756
- // A STATE NOTHING CAN ENTER CANNOT BE ADDRESSED. The base state is the app at rest —
757
- // the conversation itself — and `stateOrder` excludes it, so `resolveLatch` can never
758
- // rank a base-state instance and the pill would never appear.
759
- if (sname === Object.keys(states)[0])
760
- report("error", src, `state "${sname}": it is the BASE state — the app at rest, which the priority ladder excludes by construction (stateOrder is every state BUT the base). A latch here can never resolve, so no pill would ever draw. Declare it on a state something ARRIVES into`);
761
- }
762
728
  }
763
729
  }
764
730
 
@@ -778,8 +744,14 @@ const PLATFORM_HANDLERS = new Set(["getDetail"]); // named handlers needing no f
778
744
  // silently disable every rule after it.
779
745
  const credentialDefs = new Set();
780
746
  {
781
- const nodesHome = resolve(DESIGN_ROOT, "..", "nodes");
747
+ // Every tier's node packages: the marketplace's and each org's, all at <tier>/nodes/.
748
+ const nodesHomes = [];
782
749
  try {
750
+ for (const tier of readdirSync(DESIGN_ROOT)) nodesHomes.push(join(DESIGN_ROOT, tier, "nodes"));
751
+ } catch {
752
+ /* no design root: nothing declares a credential */
753
+ }
754
+ for (const nodesHome of nodesHomes) try {
783
755
  for (const pkg of readdirSync(nodesHome)) {
784
756
  try {
785
757
  for (const f of readdirSync(join(nodesHome, pkg, "credentials"))) if (isDefFile(f)) credentialDefs.add(defName(f));
@@ -859,24 +831,8 @@ for (const orgDir of [DS, ...orgDirs]) {
859
831
  if (f.endsWith(".js") && !declared.has(f.slice(0, -3)))
860
832
  report("error", join(folder, f), `${f} is a lifecycle handler no manifest opted into. Add "${f.slice(0, -3)}" to the manifest's lifecycle array, or delete the file — un-opted code never runs`);
861
833
 
862
- /**
863
- * LATCH, RETIRED FROM THE MANIFEST (2026-08-31, MCP guide §The Component Latch).
864
- *
865
- * It moved to the STATE, in the app's own tree, beside that state's `layout:` and
866
- * `preview:`. A component said one thing about itself for the whole of its life, but a
867
- * page is addressable when it IS the page and not when it is a summary in the flow, and
868
- * only the state knows which of those is on screen.
869
- *
870
- * An ERROR rather than a silent ignore: nothing reads this key any more, so a manifest
871
- * still carrying it declares an intent that never happens, and the author has no way to
872
- * tell that from a latch that simply does not work.
873
- */
874
834
  if (readDef(mf).latch !== undefined)
875
- report(
876
- "error",
877
- mf,
878
- `"latch" is no longer a manifest key — it moved to the STATE (2026-08-31). Declare it on the app state this component is addressable IN, beside that state's layout: \`states: { <state>: { layout: ..., latch: { title: "..." } } }\`. Nothing reads a manifest latch, so this one produces no pill (docs/MCP_COMPLETE_GUIDE.md §The Component Latch)`,
879
- );
835
+ report("error", mf, `"latch" is retired (2026-09-07). Delete the key — nothing reads it`);
880
836
  }
881
837
  }
882
838
 
@@ -910,9 +866,20 @@ function readAppSizes(dir) {
910
866
  try {
911
867
  const sizes = {};
912
868
  for (const [k, v] of Object.entries(readDef(p).appSize ?? {})) sizes[k] = typeof v === "string" ? v : v?.$value;
869
+ // `flex` IS THE SDK'S OWN WORD, NEVER A TOKEN (docs.unoverse.ai/design/apps): it means
870
+ // "fill the space remaining beside whatever core is open", on a slot and on a mounted
871
+ // template alike. A token named flex hard-codes ONE core's width and is wrong beside every
872
+ // other core: observed live 2026-09-10, an org's flex of 100% minus a 360px rail left a
873
+ // mounted grid overlapping a 480px voice core. The word is reserved; the file says so.
874
+ if (Object.prototype.hasOwnProperty.call(sizes, "flex"))
875
+ report("error", p, `app-sizes names "flex". flex is the SDK's own word (fill the space remaining beside whatever core is open), never a token: a token named flex hard-codes one core's width and is wrong beside every other core. Delete it; layouts keep writing appWidth: flex (docs.unoverse.ai/design/apps)`);
913
876
  return sizes;
914
- } catch {
915
- return null; // the file lints separately
877
+ } catch (e) {
878
+ // SAID, NOT SWALLOWED (2026-09-10): a sizes file that will not parse used to return null
879
+ // here, and the org silently inherited the foundation's set, so every width of its own
880
+ // "named no app size" and the real fault, a stray colon in the file, was never named.
881
+ report("error", p, `app-sizes is not valid ${p.endsWith(".json") ? "JSON" : "YAML"}: ${String(e?.message ?? e).split("\n")[0]}. Until it parses, none of this org's own sizes exist`);
882
+ return null;
916
883
  }
917
884
  }
918
885
  function appSizesForFile(file) {
@@ -975,13 +942,39 @@ function componentNamesForFile(file) {
975
942
  return names;
976
943
  }
977
944
 
945
+ // THE PLACES APPS DECLARE (UNOVERSE_SCREEN.md §2.2), across the whole tree. A component is shared
946
+ // by every app that shows it, so a state's `place:` is checked against every app's places, plus
947
+ // `chat`. Read once per run: every app layout under any `apps/` folder, every `Place` node in it.
948
+ let placeNamesCache;
949
+ function placeNames() {
950
+ if (placeNamesCache !== undefined) return placeNamesCache;
951
+ const names = new Set();
952
+ const walk = (n) => {
953
+ if (Array.isArray(n)) return n.forEach(walk);
954
+ if (!n || typeof n !== "object") return;
955
+ if (n.type === "Place" && typeof n.name === "string") names.add(n.name);
956
+ for (const v of Object.values(n)) walk(v);
957
+ };
958
+ const roots = [DS, ...readdirSync(DESIGN_ROOT).filter((e) => !e.startsWith(".")).map((e) => join(DESIGN_ROOT, e))];
959
+ for (const root of new Set(roots))
960
+ for (const f of jsonFiles(join(root, "apps"))) {
961
+ try {
962
+ walk(parseDef(readText(f), f));
963
+ } catch {
964
+ /* an unreadable file is reported by its own lint; it declares no place here */
965
+ }
966
+ }
967
+ placeNamesCache = names;
968
+ return names;
969
+ }
970
+
978
971
 
979
972
  // The run context: everything the extracted rule modules close over. Built here so it
980
973
  // cannot outlive the run, and passed once rather than threaded as ten parameters.
981
974
  const ctx = {
982
975
  DESIGN_ROOT, DS, orgDirs, report, spaceSteps, stepList, checkDimension, checkToken, checkCondition,
983
- appSizesForFile, componentNamesForFile, refResolves, canonicalRef, declaredProps, atomsDirExists,
984
- isFixture, isHook, isPropsExtract, isManifest, isAppPath, isTemplatePath, isTemplatePart, defRoot, readText,
976
+ appSizesForFile, componentNamesForFile, placeNames, refResolves, canonicalRef, declaredProps, atomsDirExists,
977
+ isFixture, isHook, isPropsExtract, isManifest, isAppPath, isTemplatePath, isTemplatePart, isAgentPath, defRoot, readText,
985
978
  };
986
979
  const walkNode = makeWalkNode(ctx);
987
980
  const lintFile = makeLintFile({ ...ctx, walkNode });
@@ -13,7 +13,7 @@
13
13
  // ── ground truth (mirrors design/_schema/unoverse.schema.json + server guards) ──
14
14
  export const PRIMITIVES = new Set([
15
15
  "Box", "Stack", "Row", "Column", "Each", "Switch", "ComponentSlot", "Timeline",
16
- "Text", "Image", "Button", "Input", "Select", "Markdown", "Skeleton", "Icon", "Ref", "Orb", "Template",
16
+ "Text", "Image", "Button", "Input", "Select", "Markdown", "Skeleton", "Icon", "Ref", "Orb", "Template", "Place",
17
17
  ]);
18
18
  export const CONDITION_KEYS = new Set(["field", "eq", "ne", "in"]);
19
19
 
@@ -78,7 +78,7 @@ export const PRIMITIVE_PROPS = {
78
78
  Column: ["children", "autoScroll", "revealOnStick", "appWidth"],
79
79
  Text: ["value"],
80
80
  Image: ["src", "alt"],
81
- Markdown: ["value", "inheritLinkColor"],
81
+ Markdown: ["value", "inheritLinkColor", "citeAction"],
82
82
  Icon: ["icon", "name"],
83
83
  Skeleton: ["variant"],
84
84
  Orb: ["state", "size"],
@@ -94,6 +94,9 @@ export const PRIMITIVE_PROPS = {
94
94
  // template's machinery. `name` addresses the manifest's `templates:` entry;
95
95
  // `frame` is the dressing drawn around it when occupied.
96
96
  Template: ["name", "frame", "template", "director", "appWidth"],
97
+ // A PLACE (UNOVERSE_SCREEN.md §2.2): a named spot the screen shows interfaces into.
98
+ // `holds` is one or many; `frame` and `fallback` work as they do on a ComponentSlot.
99
+ Place: ["name", "holds", "frame", "fallback", "appWidth"],
97
100
  Timeline: ["user", "assistant", "userData", "assistantData", "autoScroll"],
98
101
  };
99
102
 
@@ -25,10 +25,12 @@ const SEARCH_KEYS = ["component", "type", "include", "pick", "items"];
25
25
  // The `object_type`s a place may admit. Apps and skills are absent by construction: the
26
26
  // page's own searches are SILENT (no app unlocked, no tool minted, no card lane, no
27
27
  // director woken), or every place would rain cards onto a page still assembling itself.
28
- const QUERY_TYPES = ["services", "images", "needs", "actions"];
28
+ // `products` since migration 035 (2026-09-05; `services` retired 2026-09-07, `actions` with it:
29
+ // no row is written as one). Each word maps to a declared spatial type (guarded by a test).
30
+ const QUERY_TYPES = ["products", "images", "needs"];
29
31
 
30
32
  export function makeWalkNode(ctx) {
31
- const { report, checkCondition, checkDimension, checkToken, appSizesForFile, componentNamesForFile, refResolves, canonicalRef, declaredProps, atomsDirExists, stepList, spaceSteps, isAppPath, isTemplatePath, defRoot } = ctx;
33
+ const { report, checkCondition, checkDimension, checkToken, appSizesForFile, componentNamesForFile, refResolves, canonicalRef, declaredProps, atomsDirExists, stepList, spaceSteps, isAppPath, isTemplatePath, isTemplatePart, defRoot } = ctx;
32
34
  // One director per LAYOUT FILE, tracked for this run only (each file is walked once).
33
35
  const directorsSeen = new Map();
34
36
 
@@ -36,6 +38,13 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
36
38
  if (Array.isArray(node)) return node.forEach((n) => walkNode(n, file, root, widthCap));
37
39
  if (!node || typeof node !== "object") return;
38
40
 
41
+ // THE ✕ BELONGS TO THE TEMPLATE'S LAYOUT, NEVER TO A PART (2026-09-07). `setValue` writes
42
+ // the interface's OWN slice (docs/design/state.md) and a part is its own interface, so a
43
+ // close inside a part retracts the PART into the chat column while the page stays open
44
+ // beside it (observed live: a page's hero, ✕ and all, sitting in the flow).
45
+ if (node.type === "Ref" && node.ref === "close-button" && isTemplatePart(file))
46
+ report("error", file, `a close-button inside a template PART writes the part's own slice, not the template's — the page stays open and the part falls into the chat. Move the ✕ to the template's layout (layouts/<state>.yaml), where its setValue writes the template's state`);
47
+
39
48
  // $include — resolves against the DEFINITION ROOT (layouts/ states/ components/…)
40
49
  if (typeof node.$include === "string") {
41
50
  const a = defPath(root, node.$include);
@@ -129,8 +138,9 @@ function walkNode(node, file, root, widthCap = null, isLayoutRoot = false) {
129
138
  report("error", file, `a delivery band has no "${k}". It reads ${DELIVERY_KEYS.map((x) => `"${x}"`).join(", ")} (§9b; a place that names a component is a search place)`);
130
139
  if (d.pick !== undefined && (typeof d.pick !== "number" || d.pick < 1))
131
140
  report("error", file, `director.pick is a NUMBER — how many the director keeps, a cap the machine enforces (§9e rule 9)`);
132
- if (d.rules !== undefined && typeof d.rules !== "string")
133
- report("error", file, `director.rules is written like a brief: one string of English (§9b)`);
141
+ // NOTHING READS `rules`: the director's model was removed (UNOVERSE_SCREEN.md §2.7).
142
+ if (d.rules !== undefined)
143
+ report("warn", file, `director.rules is ignored: no model reads it any more. A band holds what arrives in search rank, up to pick. Remove it`);
134
144
  if (d.preview !== undefined && (!Array.isArray(d.preview) || d.preview.some((c) => typeof c !== "string")))
135
145
  report("error", file, `director.preview is an array of component names — Studio's stand-ins until a real run exists (§9b rule 6)`);
136
146
  else if (Array.isArray(d.preview)) {
@@ -96,7 +96,7 @@
96
96
  },
97
97
  "template": {
98
98
  "type": "string",
99
- "description": "A Handlebars template resolved against the node's input context before the request is sent.\n\nFive roots:\n signal.<sourceId>.<outputHandle>.<field> upstream node output, e.g. {{signal.inputtrigger1.output.message}}\n config.<field> this node's own settings\n credentials.<name>.<field> this node's resolved credential\n services.<connector> RUNTIME service wiring, e.g. {{#unless services.mcpService.tools}}\n prompt.<blockName> a PROMPT BLOCK from the library (alias: blocks.<name>)\n\nThe services root exists because some request shaping depends on what is WIRED rather than configured, a fact only the executor knows at run time.\n\nThe prompt root is why a manifest must NEVER hardcode instruction text. Blocks live in prompts/blocks/**/*.md, are authored and toggled in Studio, and are camelCased from the filename (markdown-guidelines.md becomes {{prompt.markdownGuidelines}}). A copy of a block's words baked into a node is a fork that silently stops tracking the block. Text belongs in the library; the node references it. This is the prompt-side twin of the SDK owning no styles.\n\nEvery root works in ANY template field, including a user's own systemPrompt: that is what lets an author compose blocks and upstream values into a prompt without the node knowing anything about it.\n\nThere is NO {{input.*}} root: a wrong path resolves to EMPTY silently. Array elements and object keys are dot segments, never brackets: records.0.Name, not records[0].Name."
99
+ "description": "A Handlebars template resolved against the node's input context before the request is sent.\n\nFive roots:\n signal.<sourceId>.<outputHandle>.<field> upstream node output, e.g. {{signal.inputtrigger1.output.message}}\n config.<field> this node's own settings\n credentials.<name>.<field> this node's resolved credential\n services.<connector> RUNTIME service wiring, e.g. {{#unless services.mcpService.tools}}\n prompt.<blockName> a PROMPT BLOCK from the library (alias: blocks.<name>)\n\nThe services root exists because some request shaping depends on what is WIRED rather than configured, a fact only the executor knows at run time.\n\nThe prompt root is why a manifest must NEVER hardcode instruction text. Blocks live in design/marketplace/blocks/**/*.md, are authored and toggled in Studio, and are camelCased from the filename (markdown-guidelines.md becomes {{prompt.markdownGuidelines}}). A copy of a block's words baked into a node is a fork that silently stops tracking the block. Text belongs in the library; the node references it. This is the prompt-side twin of the SDK owning no styles.\n\nEvery root works in ANY template field, including a user's own systemPrompt: that is what lets an author compose blocks and upstream values into a prompt without the node knowing anything about it.\n\nThere is NO {{input.*}} root: a wrong path resolves to EMPTY silently. Array elements and object keys are dot segments, never brackets: records.0.Name, not records[0].Name."
100
100
  }
101
101
  }
102
102
  }
@@ -128,6 +128,11 @@
128
128
  "type": "number",
129
129
  "minimum": 1
130
130
  },
131
+ "concurrency": {
132
+ "type": "integer",
133
+ "minimum": 1,
134
+ "description": "At most this many of the call in flight at once, in the process, per credential; the whole call, polling included. A vendor's limit, declared on the node's call once so every caller queues behind it. Absent means unbounded."
135
+ },
131
136
  "okOn": {
132
137
  "type": "array",
133
138
  "description": "HTTP statuses that are an ANSWER rather than a failure (e.g. [404] on a lookup), passed to the projection instead of thrown.",
@@ -347,6 +352,47 @@
347
352
  },
348
353
  "additionalProperties": false
349
354
  },
355
+ "repeat": {
356
+ "type": "object",
357
+ "required": [
358
+ "calls",
359
+ "until",
360
+ "maxTurns"
361
+ ],
362
+ "additionalProperties": false,
363
+ "description": "GO ROUND IN TURNS, the fourth loop after `paginate`, `chunk` and `poll`. `poll` asks one question until the answer changes; `repeat` asks different questions, each chosen by the last reply, until a reply says done: walking a tree a branch at a time, narrowing a search, letting a model ask for more before it answers.\n\nA turn is `calls`, a short list in this file's own call grammar, made in order. Within a turn a later call reads an earlier one as `calls.<name>`; the turn before is `previous.<name>`, and `previous` is null on the first turn. A call carrying `repeat` makes no request of its own.\n\nThe reply this call's `name` holds is `{ last, turns, stopped }`: the final turn's calls, EVERY turn's calls in order (the path, which is the lineage of the answer), and why it ended (`until`, `maxTurns`, `stuck`). Every turn is also drawn on the run's timeline.\n\nThere is a platform ceiling of 20 turns whatever `maxTurns` says.",
364
+ "properties": {
365
+ "calls": {
366
+ "type": "array",
367
+ "minItems": 1,
368
+ "items": {
369
+ "$ref": "#/definitions/call"
370
+ },
371
+ "description": "ONE TURN: the calls made in order each time round. Every one settles; a stream cannot be read by the next call."
372
+ },
373
+ "until": {
374
+ "$ref": "_defs.schema.json#/definitions/expression",
375
+ "description": "Done when this is true, asked after every turn over that turn's calls, e.g. \"return !!calls.pick.answer\"."
376
+ },
377
+ "maxTurns": {
378
+ "anyOf": [
379
+ {
380
+ "type": "integer",
381
+ "minimum": 1
382
+ },
383
+ {
384
+ "type": "string"
385
+ }
386
+ ],
387
+ "description": "The author's bound on turns: a number, or a template such as \"{{ config.maxTurns }}\". Borrowed from toolExchange."
388
+ },
389
+ "stuckAfterRepeats": {
390
+ "type": "integer",
391
+ "minimum": 2,
392
+ "description": "Stop when a turn is identical to the one before it this many times running: a walk that keeps choosing the same branch is not getting anywhere. Borrowed from toolExchange."
393
+ }
394
+ }
395
+ },
350
396
  "chunk": {
351
397
  "type": "object",
352
398
  "required": [
@@ -443,6 +489,14 @@
443
489
  "description": "One message, in the same two forms a `body` takes: an OBJECT whose leaves are {{ }} templates and `return` expressions, or a single expression when the message's SHAPE is conditional."
444
490
  }
445
491
  },
492
+ "keep": {
493
+ "type": "object",
494
+ "description": "DUPLEX ONLY. EVENTS WORTH REMEMBERING UNDER A NAME OF YOUR OWN.\n\n`seen` holds the latest event OF EACH TYPE, which is enough until two different things share one type. OpenAI's `response.output_item.done` ends a function call AND the model's own message, so the message overwrites the call and takes its `call_id` with it — and a reply that needs that id has nowhere left to read it. Measured live 2026-09-22: the answer could not be addressed, the model waited for a result that never came, and the caller heard silence.\n\nEach key names a slot in `seen`, and its expression decides whether THIS event belongs there, with the event in scope as `response`. A truthy result stores it; anything else leaves the slot as it was. So a manifest says what matters to it rather than the runtime guessing which vendor shapes are worth keeping.\n\nSlots are written BEFORE the events and send rows run, exactly as `seen[type]` is, so a row firing on this event already sees it.",
495
+ "additionalProperties": {
496
+ "$ref": "_defs.schema.json#/definitions/expression",
497
+ "description": "True when this event should be kept under this name."
498
+ }
499
+ },
446
500
  "close": {
447
501
  "type": "array",
448
502
  "description": "DUPLEX ONLY. Messages sent once, IN ORDER, before the socket is closed. The mirror of `open`, and needed for the same reason: Nova requires contentEnd, promptEnd and sessionEnd in that order to end a session cleanly, and a socket dropped without them leaves the vendor holding a session open and billing for it. Vendors that need no teardown simply omit this.",
@@ -533,6 +587,11 @@
533
587
  "const": "ws"
534
588
  }
535
589
  }
590
+ },
591
+ {
592
+ "required": [
593
+ "repeat"
594
+ ]
536
595
  }
537
596
  ]
538
597
  }
@@ -690,7 +749,7 @@
690
749
  ]
691
750
  }
692
751
  ],
693
- "description": "The value handed back to the CALLER. A service call returns one value; it does not emit on output connectors, which is why this is `returns` and not `map`. In scope: `response` (the LAST call's reply), `calls.<name>`, `params`, `config`, `user`.\n\nMAY ALSO BE A LITERAL. An object or array is returned exactly as written, with nothing evaluated — for a method that hands back a constant rather than shaping a reply. `getSchema` is the case: tool discovery is a fixed document, and expressing it as a `return { ... }` string meant a large object encoded inside YAML with every inner quote escaped, which no editor could check. Only a STRING is code."
752
+ "description": "The value handed back to the CALLER. A service call returns one value; it does not emit on output connectors, which is why this is `returns` and not `map`. In scope: `response` (the LAST call's reply), `calls.<name>`, `params`, `user`. NOT `config`: a reply goes to a model, and a box's settings are the author's, never the model's; the calls read config to build their requests, server-side, and that is where it stays.\n\nMAY ALSO BE A LITERAL. An object or array is returned exactly as written, with nothing evaluated — for a method that hands back a constant rather than shaping a reply. `getSchema` is the case: tool discovery is a fixed document, and expressing it as a `return { ... }` string meant a large object encoded inside YAML with every inner quote escaped, which no editor could check. Only a STRING is code."
694
753
  }
695
754
  },
696
755
  "additionalProperties": false
@@ -2,7 +2,7 @@
2
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
3
  "$id": "https://docs.unoverse.ai/schemas/nodes/audio.schema.json",
4
4
  "title": "Unoverse node audio lane",
5
- "description": "api/audio.yaml — how a duplex voice node is wired to the platform's audio lane. Only meaningful beside a `transport: ws` call.\n\nWHY THIS FILE EXISTS, and it is not a design preference. There are TWO sockets in a voice call. The VENDOR socket lives in api/run.yaml and is the node's conversation with OpenAI, xAI or Nova. The AUDIO LANE is the platform's own socket to the browser, and it exists for exactly ONE reason: MCP cannot carry binary audio.\n\nSo the rule that keeps this file small: EVERYTHING THAT IS NOT AUDIO BELONGS IN `events`. Transcripts, tool results, speech state, usage — all of it reaches the client over MCP streaming already, by landing on an output connector like any other node's output. Nothing needs a side channel to get there. If something non-audio is being put in this file, the reason is almost always that it was easier to reach the lane than to declare an output, and that is the wrong trade: an output is visible on the canvas, wirable, and testable, and a side channel is none of those.\n\nWHAT THE EXECUTOR CONTRIBUTES. Everything here names computation rather than describing data, which is why it is a handful of keys rather than a body template. Resampling is an interpolation over samples. Coalescing is a timer and a byte budget. Barge-in is discarding a buffer rather than flushing it. None of those can be written as an expression, and all of them are identical for every vendor, which is exactly the test for belonging to the executor (DECLARATIVE_NODES.md §2).",
5
+ "description": "api/audio.yaml \u2014 how a duplex voice node is wired to the platform's audio lane. Only meaningful beside a `transport: ws` call.\n\nWHY THIS FILE EXISTS, and it is not a design preference. There are TWO sockets in a voice call. The VENDOR socket lives in api/run.yaml and is the node's conversation with OpenAI, xAI or Nova. The AUDIO LANE is the platform's own socket to the browser, and it exists for exactly ONE reason: MCP cannot carry binary audio.\n\nSo the rule that keeps this file small: EVERYTHING THAT IS NOT AUDIO BELONGS IN `events`. Transcripts, tool results, speech state, usage \u2014 all of it reaches the client over MCP streaming already, by landing on an output connector like any other node's output. Nothing needs a side channel to get there. If something non-audio is being put in this file, the reason is almost always that it was easier to reach the lane than to declare an output, and that is the wrong trade: an output is visible on the canvas, wirable, and testable, and a side channel is none of those.\n\nWHAT THE EXECUTOR CONTRIBUTES. Everything here names computation rather than describing data, which is why it is a handful of keys rather than a body template. Resampling is an interpolation over samples. Coalescing is a timer and a byte budget. Barge-in is discarding a buffer rather than flushing it. None of those can be written as an expression, and all of them are identical for every vendor, which is exactly the test for belonging to the executor (DECLARATIVE_NODES.md \u00a72).",
6
6
  "type": "object",
7
7
  "properties": {
8
8
  "in": {
@@ -14,7 +14,7 @@
14
14
  "properties": {
15
15
  "resampleTo": {
16
16
  "type": "number",
17
- "description": "Sample rate the VENDOR wants, in Hz. The client captures at 16000 and vendors disagree: OpenAI and xAI want 24000, Nova wants 16000. When this differs from the incoming rate the executor resamples by linear interpolation before wrapping.\n\nThis is a rate, not a switch, because getting it wrong is not an error anywhere — the vendor accepts the bytes and transcribes them at the wrong speed, so the model hears a chipmunk and the failure looks like poor accuracy rather than a misconfiguration."
17
+ "description": "Sample rate the VENDOR wants, in Hz. The client captures at 16000 and vendors disagree: OpenAI and xAI want 24000, Nova wants 16000. When this differs from the incoming rate the executor resamples by linear interpolation before wrapping.\n\nThis is a rate, not a switch, because getting it wrong is not an error anywhere \u2014 the vendor accepts the bytes and transcribes them at the wrong speed, so the model hears a chipmunk and the failure looks like poor accuracy rather than a misconfiguration."
18
18
  },
19
19
  "message": {
20
20
  "anyOf": [
@@ -26,6 +26,17 @@
26
26
  }
27
27
  ],
28
28
  "description": "The vendor's envelope for a chunk of microphone audio, with the chunk in scope as `audio` ({ base64, bytes, rate }). An OBJECT whose leaves are templates is the normal case; an expression when the shape is conditional. OpenAI wants { type: 'input_audio_buffer.append', audio }, Nova wants an audioInput event inside its content block. This is the description half; the resampling above is the computation half."
29
+ },
30
+ "laneCodecs": {
31
+ "type": "array",
32
+ "items": {
33
+ "type": "string",
34
+ "enum": [
35
+ "mulaw",
36
+ "pcm16"
37
+ ]
38
+ },
39
+ "description": "Lane codecs this VENDOR can take raw, so a lane already speaking one is not converted twice. Absent, which is the normal case, means every frame is decoded and resampled to `resampleTo` as it always was.\n\nIt exists because a telephone lane is 8 kHz G.711 mu-law and some vendors accept exactly that. Naming `mulaw` here says the node's own handshake asks the vendor for mu-law, so the carrier's bytes go straight through in both directions: no decode, no interpolation up to 24 kHz and back down, no re-compand. None of that work could improve a phone call, which is 8 kHz whatever is done to it, and every step of it rounds the edges off a little further.\n\nTHE TWO HALVES MUST AGREE. This only says the executor may stop converting; the handshake in api/run.yaml is what actually asks the vendor for that codec. Declaring one without the other is silence or noise, not an error: a vendor still sending PCM whose frames are handed untouched to a telephone, or the reverse."
29
40
  }
30
41
  },
31
42
  "additionalProperties": false
@@ -48,11 +59,11 @@
48
59
  },
49
60
  "done": {
50
61
  "type": "string",
51
- "description": "The inbound event type meaning this utterance is finished, e.g. response.output_audio.done. Flushes whatever is still buffered and then signals SPEECH_ENDED.\n\nORDER MATTERS and the executor guarantees it: the flush goes out BEFORE the end signal. SPEECH_ENDED marks the END of the utterance and the client finishes playback as soon as its queue drains, so a frame sent after it can arrive on a player that has already stopped and reset — dropped, or replayed as a stray fragment.\n\nThe executor also sends SPEECH_STARTED on the FIRST chunk of each utterance, without it needing to be declared: the vendor has no 'about to speak' event, so the first delta after silence IS the start. The client sets up playback on it."
62
+ "description": "The inbound event type meaning this utterance is finished, e.g. response.output_audio.done. Flushes whatever is still buffered and then signals SPEECH_ENDED.\n\nORDER MATTERS and the executor guarantees it: the flush goes out BEFORE the end signal. SPEECH_ENDED marks the END of the utterance and the client finishes playback as soon as its queue drains, so a frame sent after it can arrive on a player that has already stopped and reset \u2014 dropped, or replayed as a stray fragment.\n\nThe executor also sends SPEECH_STARTED on the FIRST chunk of each utterance, without it needing to be declared: the vendor has no 'about to speak' event, so the first delta after silence IS the start. The client sets up playback on it."
52
63
  },
53
64
  "interruptOn": {
54
65
  "type": "string",
55
- "description": "The inbound event type meaning the USER started talking over the model, e.g. input_audio_buffer.speech_started. Buffered audio is DISCARDED rather than flushed.\n\nThe distinction from a flush is the whole point of barge-in: flushing plays a fragment of a sentence the person already interrupted, which is the most obvious way a voice call feels broken.\n\nNO CONTROL STATE OF ITS OWN. The client cuts playback on USER_SPEECH_STARTED, which `control.userSpeaking` already sends on this same event — so the server's whole job here is to throw away the audio that was talked over, so it cannot be flushed later."
66
+ "description": "The inbound event type meaning the USER started talking over the model, e.g. input_audio_buffer.speech_started. Buffered audio is DISCARDED rather than flushed.\n\nThe distinction from a flush is the whole point of barge-in: flushing plays a fragment of a sentence the person already interrupted, which is the most obvious way a voice call feels broken.\n\nNO CONTROL STATE OF ITS OWN. The client cuts playback on USER_SPEECH_STARTED, which `control.userSpeaking` already sends on this same event \u2014 so the server's whole job here is to throw away the audio that was talked over, so it cannot be flushed later."
56
67
  },
57
68
  "coalesceBytes": {
58
69
  "type": "number",
@@ -85,6 +96,18 @@
85
96
  "userStopped": {
86
97
  "type": "string",
87
98
  "description": "The vendor event meaning the person stopped talking, e.g. input_audio_buffer.speech_stopped. Sends USER_SPEECH_ENDED on the lane."
99
+ },
100
+ "toolUse": {
101
+ "type": "string",
102
+ "description": "The vendor event meaning work has started away from the conversation, e.g. a hand-off to a backend (session.delegation.created). Sends TOOL_USE on the lane, which the client's call state shows as thinking. Tool calls the platform runs itself send it without this."
103
+ },
104
+ "toolUseCompleted": {
105
+ "type": "string",
106
+ "description": "The vendor event meaning that work has come back, e.g. the vendor acknowledging the answer (session.commentary.appended). Sends TOOL_USE_COMPLETED on the lane."
107
+ },
108
+ "endWhen": {
109
+ "$ref": "_defs.schema.json#/definitions/expression",
110
+ "description": "THE MODEL ENDING THE CALL ITSELF, tested against every vendor event with it in scope as `response`. True ends the session exactly as a hang-up does.\n\n`endOn` above is the LANE's list and every entry on it means the PERSON left: a carrier's stop frame, a browser tab closing. Nothing there can say the ASSISTANT is finished, and a live voice model may send no end-of-call event of its own, so a call whose business was done stayed open: it said goodbye, stopped talking, and held the line until the idle timer fired minutes later. The caller hears silence and the session bills for it.\n\nWhat counts is the node's to decide. For a vendor with function calling the natural answer is a tool the model may call, so the expression tests for that name. Absent, nothing changes: only the lane ends a call."
88
111
  }
89
112
  },
90
113
  "additionalProperties": false
@@ -135,9 +135,10 @@
135
135
  "textarea",
136
136
  "slider",
137
137
  "checkboxes",
138
- "domainSelector"
138
+ "domainSelector",
139
+ "spatialObjects"
139
140
  ],
140
- "description": "IMPLEMENTED widgets only, verified against the renderer in apps/canvas/src/components/workflow/ConfigurationForm/FieldRenderer.jsx:\n\n toggle a boolean switch\n select an enum picker\n textarea a multi-line box (FieldRenderer.jsx:248). Pair with ui:options.rows\n slider a number, dragged rather than typed (:162)\n checkboxes an array of enum values, all visible at once (:208)\n domainSelector an array of hostnames (:195)\n\nNOT `color`. The retired Note node declared `ui:widget: color` and the renderer has never implemented it, so it fell through to a plain text input — a setting that looked bespoke and was not. Adding a value here without a branch in FieldRenderer reproduces exactly that: it lints clean and silently renders as something else."
141
+ "description": "IMPLEMENTED widgets only, verified against the renderer in apps/canvas/src/components/workflow/ConfigurationForm/FieldRenderer.jsx:\n\n toggle a boolean switch\n select an enum picker\n textarea a multi-line box (FieldRenderer.jsx:248). Pair with ui:options.rows\n slider a number, dragged rather than typed (:162)\n checkboxes an array of enum values, all visible at once (:208)\n domainSelector an array of hostnames (:195)\n spatialObjects an object of per-object settings (off, intelligent, on) for the objects on the canvas's map (docs/unoverse/data/spatial/objects-in-spatial.md); `ui:options.settings` narrows the choices\n\nNOT `color`. The retired Note node declared `ui:widget: color` and the renderer has never implemented it, so it fell through to a plain text input — a setting that looked bespoke and was not. Adding a value here without a branch in FieldRenderer reproduces exactly that: it lints clean and silently renders as something else."
141
142
  },
142
143
  "ui:dependencies": {
143
144
  "type": "object",