@xano/sdk 1.0.14 → 1.0.16

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 (290) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +33 -37
  3. package/dist/.build-fingerprint +1 -1
  4. package/dist/{agent-file-refresh-3J6YRVFL.js → agent-file-refresh-DBHTEFYM.js} +12 -12
  5. package/dist/{agent-skill-command-VWDMQWCT.js → agent-skill-command-LHNTU7MH.js} +74 -73
  6. package/dist/{answer-shape-AVZSKBR6.js → answer-shape-ZRQS7ZC4.js} +5 -5
  7. package/dist/{backend-dir-ISP7RVF2.js → backend-dir-AXR43HNV.js} +11 -11
  8. package/dist/{backend-slot-DZAUHLTS.js → backend-slot-7BATLL3X.js} +4 -4
  9. package/dist/bin.js +64 -63
  10. package/dist/{branch-IJTBZZFO.js → branch-SJKKUCMZ.js} +9 -9
  11. package/dist/branch-commands-KGR52SZU.js +80 -0
  12. package/dist/bundle.d.ts +2 -2
  13. package/dist/bundle.js +15 -69
  14. package/dist/{capture-GW5KNKMB.js → capture-RYBJE25P.js} +5 -5
  15. package/dist/{chunk-Z3DQ7ULY.js → chunk-23GEFHRX.js} +236 -17
  16. package/dist/{chunk-3H7R4ISR.js → chunk-2DUYJR5N.js} +2 -2
  17. package/dist/{chunk-MFWF2NZJ.js → chunk-2H5BQRHF.js} +2 -2
  18. package/dist/{chunk-O44MJTLR.js → chunk-35SI4GBM.js} +3 -3
  19. package/dist/{chunk-QKHNJ7LE.js → chunk-3ZV23FVR.js} +5 -5
  20. package/dist/{chunk-HKI5Y5KW.js → chunk-47XIVDJ6.js} +14 -14
  21. package/dist/{chunk-ICK36EGF.js → chunk-4EVDCSEY.js} +2 -2
  22. package/dist/{chunk-FBSGFPZ4.js → chunk-4XGZ325S.js} +3 -3
  23. package/dist/{chunk-EYVIUX2T.js → chunk-4XYXUK5H.js} +76 -33
  24. package/dist/{chunk-MAXDJZQR.js → chunk-4ZBXS7YN.js} +8 -8
  25. package/dist/{chunk-ZMJRAMLA.js → chunk-52QAENY6.js} +14 -14
  26. package/dist/{chunk-2LF734YB.js → chunk-54CJ74BH.js} +4 -4
  27. package/dist/{chunk-3SZ7QRYA.js → chunk-57PGTPT3.js} +8 -8
  28. package/dist/{chunk-IKXXTRMN.js → chunk-64UVVLDT.js} +4 -4
  29. package/dist/{chunk-EQXHUWUO.js → chunk-6FCAFWD5.js} +2 -2
  30. package/dist/{chunk-4MX5LMPQ.js → chunk-6ODQ5GDZ.js} +2 -2
  31. package/dist/{chunk-HK554MDD.js → chunk-74YCPI4G.js} +7 -7
  32. package/dist/{chunk-Y5XAPLZS.js → chunk-7UQZ7C4W.js} +4 -4
  33. package/dist/{chunk-CJDPSCMX.js → chunk-7ZVQIKNL.js} +3 -3
  34. package/dist/{chunk-RVAEPPRH.js → chunk-AICWDCLJ.js} +2 -2
  35. package/dist/{chunk-WS4BA75E.js → chunk-AJBOGO5U.js} +4 -4
  36. package/dist/{chunk-2FDHIBEU.js → chunk-AJQFUJEQ.js} +8 -8
  37. package/dist/{chunk-2KOB4QPW.js → chunk-C7AYP4H6.js} +29 -20
  38. package/dist/{chunk-XCFQLP6G.js → chunk-DJMGDCVX.js} +8 -8
  39. package/dist/{chunk-VBSCWV5H.js → chunk-DLD4FVRP.js} +54 -54
  40. package/dist/{chunk-Q7DGTQ5G.js → chunk-E34VGSCI.js} +2 -1
  41. package/dist/{chunk-YR3MNGWZ.js → chunk-E5M5P23K.js} +8 -8
  42. package/dist/{chunk-HJZUI2ZU.js → chunk-EAZTRU75.js} +2 -2
  43. package/dist/{chunk-QX5XQEYB.js → chunk-EINZSVEU.js} +5 -5
  44. package/dist/{chunk-KMKUH2IO.js → chunk-EPB6FAR5.js} +5 -5
  45. package/dist/chunk-EUAU4QKI.js +67 -0
  46. package/dist/{chunk-IDOVZLPK.js → chunk-EXJ4Q5F6.js} +2 -2
  47. package/dist/{chunk-IHL2O7VY.js → chunk-F3JK5RIY.js} +3 -2
  48. package/dist/{chunk-W2QFR3ZJ.js → chunk-FIOC7RSU.js} +2 -2
  49. package/dist/{chunk-YEH5OIPF.js → chunk-FMXPV5JI.js} +39 -11
  50. package/dist/{chunk-GVHWIDEJ.js → chunk-FRJB3NTE.js} +10 -5
  51. package/dist/{chunk-VIRFG3WG.js → chunk-FTFAPKCW.js} +23 -7
  52. package/dist/{chunk-LL6ED5IB.js → chunk-FTS42N37.js} +2 -2
  53. package/dist/{chunk-MIS6F4HM.js → chunk-G2XSDIYS.js} +4 -4
  54. package/dist/{chunk-ZY55DO5P.js → chunk-G6BEJ3NA.js} +2 -2
  55. package/dist/{chunk-RYWNNJK5.js → chunk-GA6HTO3O.js} +2 -2
  56. package/dist/{chunk-JIKGT7DO.js → chunk-GE3JV5SI.js} +1 -1
  57. package/dist/{chunk-GCINMMFL.js → chunk-GJZMKMWO.js} +2 -2
  58. package/dist/{chunk-LW7TOIS7.js → chunk-GRZ62LLU.js} +8 -8
  59. package/dist/{chunk-6X73VFCX.js → chunk-GT7PZCTK.js} +2 -2
  60. package/dist/{chunk-HINRE3UM.js → chunk-HXPQXCOZ.js} +1821 -506
  61. package/dist/{chunk-ECQXASG3.js → chunk-IFHFJR5O.js} +2 -2
  62. package/dist/{chunk-P4OWRYE7.js → chunk-IOWNQEMW.js} +31 -31
  63. package/dist/{chunk-SUKO4SZG.js → chunk-ISIZFK5Q.js} +53 -47
  64. package/dist/{chunk-QJ25N4W6.js → chunk-IUJDUFT7.js} +4 -4
  65. package/dist/{chunk-L34DM6QB.js → chunk-JHAZK4RY.js} +3 -3
  66. package/dist/{chunk-YL3WVBR5.js → chunk-KGHJ74HF.js} +6 -6
  67. package/dist/{chunk-NUZXSIEA.js → chunk-L2O5KG5Q.js} +6 -6
  68. package/dist/{chunk-L4WG4BKJ.js → chunk-L3Q2QYIQ.js} +72 -72
  69. package/dist/{chunk-SAEIVQLP.js → chunk-LLBEPJBO.js} +3 -3
  70. package/dist/{chunk-NOW522B4.js → chunk-LWBGPPI5.js} +13 -13
  71. package/dist/{chunk-GOKRKTCX.js → chunk-MBSHONP3.js} +3 -3
  72. package/dist/{chunk-GKQTXUOW.js → chunk-MOVRSULZ.js} +2 -2
  73. package/dist/{chunk-QAEBBTYR.js → chunk-MSYMEP7Y.js} +7 -7
  74. package/dist/{chunk-Y453TW6J.js → chunk-NCERS5QH.js} +2 -2
  75. package/dist/{chunk-HXFLHA5K.js → chunk-NH5Z2NOD.js} +2 -2
  76. package/dist/{chunk-T3HNISBN.js → chunk-NJVY3GAX.js} +3 -3
  77. package/dist/{chunk-J62TYONQ.js → chunk-NQPPUNWP.js} +3 -3
  78. package/dist/{chunk-LJZIBT75.js → chunk-O7Z3LF44.js} +5 -5
  79. package/dist/{chunk-B7CPSWQX.js → chunk-OLXYZQR7.js} +7 -7
  80. package/dist/{chunk-7F3V6CFP.js → chunk-OQNYZ2OM.js} +3 -3
  81. package/dist/{chunk-DBDTQR23.js → chunk-OTQF4B37.js} +4 -4
  82. package/dist/{chunk-GBSHHNSD.js → chunk-PRSNMSVG.js} +3 -3
  83. package/dist/{chunk-DGYXCIBV.js → chunk-Q6AKSLD2.js} +2 -2
  84. package/dist/{chunk-YTQYP7UJ.js → chunk-Q7KXMIR3.js} +3 -3
  85. package/dist/{chunk-IWJ6GFST.js → chunk-QCVH32T2.js} +5 -5
  86. package/dist/{chunk-7FIMUFBP.js → chunk-QDPY7RN3.js} +3 -3
  87. package/dist/{chunk-DLDYQNGP.js → chunk-QIT2GGNB.js} +3 -3
  88. package/dist/{chunk-J3XLCYTQ.js → chunk-QSJH5AFU.js} +244 -173
  89. package/dist/{chunk-DERQSEB5.js → chunk-R7DS2TRZ.js} +38 -22
  90. package/dist/{chunk-BEKEOXNG.js → chunk-RGPHFHJU.js} +2 -2
  91. package/dist/{chunk-5FJ4M4HB.js → chunk-RHH6SCB4.js} +17 -32
  92. package/dist/{chunk-Z4BQPABS.js → chunk-RIT3WBBX.js} +4 -4
  93. package/dist/{chunk-45K2QZBR.js → chunk-RKNCISPM.js} +3 -3
  94. package/dist/{chunk-6LJS4M6P.js → chunk-RKTVXFBV.js} +5 -5
  95. package/dist/{chunk-AXNX4NWN.js → chunk-RLQX6LHW.js} +37 -37
  96. package/dist/{chunk-FIERONKM.js → chunk-ROWYW3JF.js} +2 -2
  97. package/dist/{chunk-LSJ3SQEU.js → chunk-RVWWNNZQ.js} +4 -4
  98. package/dist/{chunk-LPQZICYN.js → chunk-S7MVI4W7.js} +7 -7
  99. package/dist/{chunk-4MIV244X.js → chunk-SGEOXJIH.js} +9 -2
  100. package/dist/{chunk-QRMKQYCB.js → chunk-SINL5WMI.js} +2 -2
  101. package/dist/{chunk-Z6N5N4MN.js → chunk-SIW2HT2H.js} +21 -5
  102. package/dist/{chunk-IEDQT4Z3.js → chunk-SOAZIMWL.js} +12 -12
  103. package/dist/{chunk-RPBB7P4Q.js → chunk-SVQMDVND.js} +87 -16
  104. package/dist/{chunk-45ZUMF4E.js → chunk-TPUAXIPR.js} +2 -2
  105. package/dist/{chunk-HMYJOQXT.js → chunk-TXU34ELY.js} +25 -25
  106. package/dist/{chunk-MTBKTGZT.js → chunk-U4UAWGIT.js} +12 -8
  107. package/dist/{chunk-76SBT7KS.js → chunk-U56HK2RG.js} +7 -5
  108. package/dist/{chunk-RV2BDU7V.js → chunk-UDW2KAVF.js} +6 -6
  109. package/dist/{chunk-NDV6CBR7.js → chunk-UH5VQGNR.js} +2 -2
  110. package/dist/{chunk-75QC66XI.js → chunk-V2MIBJZU.js} +2 -2
  111. package/dist/{chunk-RDZBXTZ3.js → chunk-VAQPQXOI.js} +4 -4
  112. package/dist/{chunk-XPSDDTUZ.js → chunk-VCFRALU7.js} +3 -3
  113. package/dist/{chunk-5KJBWIDZ.js → chunk-VQDVEHDB.js} +2 -2
  114. package/dist/{chunk-6ILHYSLR.js → chunk-WAP5362D.js} +5 -5
  115. package/dist/{chunk-XY4OBD26.js → chunk-WGKKDGSA.js} +4 -4
  116. package/dist/{chunk-UQ2OD7D4.js → chunk-WVVUE7LU.js} +14 -7
  117. package/dist/{chunk-LB76VK6D.js → chunk-WXQ7BHVQ.js} +7 -7
  118. package/dist/{chunk-7REDHC4N.js → chunk-X5NF3ZXW.js} +69 -14
  119. package/dist/{chunk-5W7S2SCA.js → chunk-XAE4NIZ2.js} +4 -4
  120. package/dist/{chunk-SPLRKCFV.js → chunk-XDGLYIB2.js} +2 -2
  121. package/dist/{chunk-BSGU4HS6.js → chunk-XKMZYU5B.js} +96 -65
  122. package/dist/{chunk-OLQN4Z5R.js → chunk-Y3RH35KM.js} +47 -47
  123. package/dist/{chunk-YFQCDLCQ.js → chunk-YHT7TDSH.js} +14 -14
  124. package/dist/{chunk-KDEU5FUJ.js → chunk-YJXJOMXW.js} +3 -3
  125. package/dist/{chunk-N6LGLNAC.js → chunk-YPLHVRMS.js} +4 -4
  126. package/dist/{chunk-WS2X5BB2.js → chunk-YYBBJPCL.js} +5 -5
  127. package/dist/{chunk-ZOHEHIFS.js → chunk-YYDM4DNP.js} +2 -2
  128. package/dist/{chunk-MYIIBV6A.js → chunk-ZF4LCHCT.js} +5 -5
  129. package/dist/{chunk-GRXX2TOJ.js → chunk-ZHFSIQ6E.js} +2 -2
  130. package/dist/{chunk-CB67GIR3.js → chunk-ZJQFKBX7.js} +7 -7
  131. package/dist/{chunk-ZRXDPCMN.js → chunk-ZYZ7GRX3.js} +2 -2
  132. package/dist/{chunk-5TWLVFYB.js → chunk-ZZC5VSLP.js} +4 -4
  133. package/dist/cli.d.ts +3 -3
  134. package/dist/cli.js +62 -61
  135. package/dist/codegen-command-NAY6YAOD.js +183 -0
  136. package/dist/codegen.d.ts +3 -3
  137. package/dist/codegen.js +5 -5
  138. package/dist/{commands-5ILSWDSV.js → commands-Z2QZOORB.js} +3 -3
  139. package/dist/{completion-UNKBVVDT.js → completion-LFXXNQGR.js} +3 -3
  140. package/dist/{config-NTOASFCA.js → config-7GGINOFY.js} +4 -4
  141. package/dist/{deploy-command-WESYWFJN.js → deploy-command-PBM3S4ZL.js} +69 -68
  142. package/dist/{deploy-source-ZQQNMDFX.js → deploy-source-JW7DAN75.js} +32 -32
  143. package/dist/{dev-env-sync-4XJT7WOT.js → dev-env-sync-FHJTFH3V.js} +63 -62
  144. package/dist/{diagnostics-FNVNRYMB.js → diagnostics-T3RN3372.js} +2 -2
  145. package/dist/{display-name-hint-MYXCCAOP.js → display-name-hint-5GLJGPQ6.js} +11 -11
  146. package/dist/{emit-YLt3GfsZ.d.ts → emit-t-gDE1BL.d.ts} +181 -93
  147. package/dist/env-example-refresh-HHEGMFNH.js +136 -0
  148. package/dist/{env-pull-command-SK5FS477.js → env-pull-command-FFPNRVWD.js} +52 -52
  149. package/dist/{env-target-TEFSYACA.js → env-target-XHVRZXHX.js} +14 -14
  150. package/dist/{env-var-command-IJHKA2WJ.js → env-var-command-DJS62YRR.js} +41 -41
  151. package/dist/{ephemeral-VLPRDNEJ.js → ephemeral-2DXWP3VK.js} +9 -9
  152. package/dist/{ephemeral-command-WCO5J4SN.js → ephemeral-command-VLQIQ5TS.js} +52 -52
  153. package/dist/{ephemeral-state-RUOU2GFS.js → ephemeral-state-56XEDUJW.js} +12 -12
  154. package/dist/{generate-command-3WCOUOEQ.js → generate-command-PSDIIOTU.js} +89 -88
  155. package/dist/{gitignore-WYS3GMOX.js → gitignore-PMJ6MFNA.js} +15 -15
  156. package/dist/{guards-PPIBIMFZ.js → guards-YICHJKX3.js} +51 -15
  157. package/dist/{impersonate-command-UMYVQTCG.js → impersonate-command-IKV4KUYA.js} +37 -37
  158. package/dist/{import-T4ZTOTBT.js → import-VJQGIS33.js} +5 -5
  159. package/dist/index.d.ts +653 -222
  160. package/dist/index.js +29 -28
  161. package/dist/init-command-LEQIE6GC.js +143 -0
  162. package/dist/{init-modules-7KALFI5C.js → init-modules-G47Q7ABV.js} +8 -8
  163. package/dist/{init-web-DYE2FEXL.js → init-web-25QJ4JWB.js} +3 -3
  164. package/dist/internal.d.ts +55 -8
  165. package/dist/internal.js +692 -503
  166. package/dist/{io-PGTCBSIQ.js → io-47TFRYDB.js} +6 -6
  167. package/dist/{keep-data-merge-OVHCIEBG.js → keep-data-merge-XCPCX7BZ.js} +38 -38
  168. package/dist/{lambda-config-reconcile-VOBVZPWS.js → lambda-config-reconcile-CC5QIP6E.js} +3 -3
  169. package/dist/{landed-F7PCHGCK.js → landed-VIUFHLCJ.js} +5 -5
  170. package/dist/{landing-record-AIHNW4AZ.js → landing-record-JQ7HZDGI.js} +22 -22
  171. package/dist/{live-diff-UMSOGPX3.js → live-diff-KJ2TWWWT.js} +14 -14
  172. package/dist/{local-engine-choice-XDGTATKJ.js → local-engine-choice-DFAMYOIF.js} +35 -35
  173. package/dist/{local-engine-command-VQWNQ7UK.js → local-engine-command-5RP2J5QZ.js} +40 -40
  174. package/dist/{local-engine-deploy-4N4NFZ4T.js → local-engine-deploy-XAEDT55W.js} +12 -12
  175. package/dist/{local-engine-lookup-AQTUGSBT.js → local-engine-lookup-WBYTY2JE.js} +2 -2
  176. package/dist/{local-engine-mcp-bridge-AMYRH4SY.js → local-engine-mcp-bridge-3H5OXBWQ.js} +5 -5
  177. package/dist/{local-engine-mcp-command-AIMNMXQG.js → local-engine-mcp-command-JSYVVZKK.js} +42 -42
  178. package/dist/{local-engine-process-OD5OSWDG.js → local-engine-process-35B2KQED.js} +7 -7
  179. package/dist/{local-engine-update-check-G3YCBXRE.js → local-engine-update-check-VXJZSIJU.js} +5 -5
  180. package/dist/{lock-HDCHD2ON.js → lock-JBKTDEDO.js} +4 -4
  181. package/dist/{lock-commands-H3YV2D6M.js → lock-commands-7VO6YWOV.js} +67 -66
  182. package/dist/{login-command-NMM3JNDZ.js → login-command-WTZUBCW6.js} +27 -27
  183. package/dist/{logout-command-7DYC6G32.js → logout-command-5BJUNK3C.js} +17 -17
  184. package/dist/{loop-DJNIHC7O.js → loop-HILLODVH.js} +15 -15
  185. package/dist/{marketplace-command-UCSHDZGO.js → marketplace-command-NMOH4XOV.js} +30 -30
  186. package/dist/{marketplace-resolve-JR4BBJ6K.js → marketplace-resolve-63QWMQZU.js} +6 -6
  187. package/dist/{meta-client-CD3TXQP6.js → meta-client-MRAMWUKV.js} +15 -15
  188. package/dist/{module-manifest-63I5GRK4.js → module-manifest-NWJWAQLQ.js} +4 -4
  189. package/dist/node.d.ts +8 -8
  190. package/dist/node.js +71 -70
  191. package/dist/{operation-outcome-2ONIIDRU.js → operation-outcome-WK7UW6PJ.js} +24 -24
  192. package/dist/{output-target-67LHZKCO.js → output-target-5PYRCCK4.js} +16 -16
  193. package/dist/{plan-disclosure-T7DF4SRJ.js → plan-disclosure-6MG4YYJV.js} +28 -28
  194. package/dist/{plugin-contributions-YYEP7IWH.js → plugin-contributions-DD6R6RL6.js} +5 -5
  195. package/dist/{plugin-prompt-GKCQKNYI.js → plugin-prompt-UX2TT5NS.js} +5 -5
  196. package/dist/{plugin-questions-P7MA3TYI.js → plugin-questions-WE2F4ZC4.js} +4 -4
  197. package/dist/{preflight-command-TJ7FURXB.js → preflight-command-3BX2WW3S.js} +75 -74
  198. package/dist/{profile-command-LDPLTJEJ.js → profile-command-GSUX3UMB.js} +28 -28
  199. package/dist/{profile-pointer-JJ7K5O2R.js → profile-pointer-RCPHVTJV.js} +4 -4
  200. package/dist/{project-dependency-X3KCWBK5.js → project-dependency-TPVV3YIX.js} +7 -7
  201. package/dist/{project-sdk-YHJZRCNB.js → project-sdk-DKZBK5H5.js} +4 -4
  202. package/dist/promote-command-3LQTXWCD.js +149 -0
  203. package/dist/{prompt-QNMJIWNI.js → prompt-OYQHQWKI.js} +4 -4
  204. package/dist/{publish-command-IIRN6NWN.js → publish-command-3BQCV4NE.js} +72 -71
  205. package/dist/pull-command-B7OVWTZD.js +171 -0
  206. package/dist/{pull-superseded-6HADGGC5.js → pull-superseded-3SSM3JFT.js} +4 -4
  207. package/dist/{raw-where-gWGr-E4t.d.ts → raw-where-CinW0keO.d.ts} +32 -4
  208. package/dist/release-command-XSDICMJE.js +153 -0
  209. package/dist/{release-ns-command-YLCQPVH3.js → release-ns-command-EVAHK4CU.js} +96 -95
  210. package/dist/{retry-command-LFZYEVRU.js → retry-command-WP4ZI6CJ.js} +8 -8
  211. package/dist/{routes-manifest-R3TQRB24.js → routes-manifest-N73THJB3.js} +16 -16
  212. package/dist/routes-manifest-file-LDUDIVFJ.js +41 -0
  213. package/dist/scaffold.js +2 -2
  214. package/dist/{secrets-file-PCNAFXNV.js → secrets-file-7XWR7HW3.js} +15 -15
  215. package/dist/{secrets-fill-command-G7NQMRXU.js → secrets-fill-command-NKCGC75L.js} +66 -65
  216. package/dist/{seed-4CD55LB4.js → seed-YKTZDS2Q.js} +13 -13
  217. package/dist/{source-resolve-U4SJR7ZA.js → source-resolve-CQGDFQQC.js} +22 -22
  218. package/dist/{static-host-MO4VDHL7.js → static-host-3HPZKVKK.js} +5 -5
  219. package/dist/{status-command-CD72PXIT.js → status-command-TBMQ3GJP.js} +38 -38
  220. package/dist/{store-AJX4MC7Y.js → store-B63BQV6R.js} +6 -6
  221. package/dist/{store-BM7SQcUt.d.ts → store-in7gSpMS.d.ts} +297 -129
  222. package/dist/sync-baseline-GRS33AB5.js +38 -0
  223. package/dist/{sync-contributions-XK6LHISZ.js → sync-contributions-RKPLZPPO.js} +9 -9
  224. package/dist/{sync-record-NE62ERA3.js → sync-record-AWFCSS4D.js} +15 -15
  225. package/dist/{table-WPRAM4VW.js → table-ONGT3JGE.js} +12 -12
  226. package/dist/{tables-command-NMTKR52H.js → tables-command-UYQ277TJ.js} +41 -41
  227. package/dist/{tenant-IIYECNWO.js → tenant-IXIW3FOI.js} +10 -10
  228. package/dist/{tenant-command-XQAWT46C.js → tenant-command-7LWZUK2V.js} +104 -103
  229. package/dist/{test-command-W4AD4KT4.js → test-command-7KTT5EAF.js} +56 -45
  230. package/dist/{tests-JWQRHFCT.js → tests-N4MMBABH.js} +6 -6
  231. package/dist/{token-P3VQ6ITJ.js → token-3TCMW2AP.js} +13 -13
  232. package/dist/{toolchain-hooks-UAJBPSTC.js → toolchain-hooks-IJWV3ZQS.js} +18 -18
  233. package/dist/{toolchain-modules-S3MPHCUI.js → toolchain-modules-PBVBCPQJ.js} +5 -5
  234. package/dist/{toolchain-peers-FQJBTKEB.js → toolchain-peers-EMOYN4U7.js} +8 -8
  235. package/dist/{tracked-backend-WWEPNUD5.js → tracked-backend-YDUUQZQF.js} +34 -34
  236. package/dist/update-check-C6KDFGMT.js +141 -0
  237. package/dist/{upgrade-command-J6LRNHYF.js → upgrade-command-ZSBTSMBR.js} +68 -67
  238. package/dist/{whoami-command-KWRP2CII.js → whoami-command-L6ERHR5K.js} +16 -16
  239. package/dist/{workspace-3YNK4XO4.js → workspace-5DPSDM4A.js} +5 -5
  240. package/dist/{workspace-binding-TTDNXHO5.js → workspace-binding-MVOWGNYW.js} +15 -15
  241. package/dist/{workspace-command-W4ANGLCZ.js → workspace-command-PKQ5TDR7.js} +100 -99
  242. package/dist/{workspace-env-6LJGCTZA.js → workspace-env-UZJZUIYV.js} +18 -12
  243. package/dist/{workspace-export-PUEXKZNS.js → workspace-export-3KMWNZDD.js} +5 -5
  244. package/dist/{writable-LMMG4AFZ.js → writable-X7BCN7XE.js} +4 -4
  245. package/dist/xano-YB6Y2IJS.js +44 -0
  246. package/dist/{xanosdk-import-PNNMZ4SF.js → xanosdk-import-HHMQDK2I.js} +10 -10
  247. package/dist/{xanosdk-project-YW3BQY2E.js → xanosdk-project-CKEUNJU4.js} +13 -13
  248. package/dist/{xdo-D4OwfF2J.d.ts → xdo-DNGZGO1j.d.ts} +50 -12
  249. package/guides/authoring.md +1 -0
  250. package/guides/codes.md +33 -3
  251. package/guides/coverage.md +2 -2
  252. package/guides/object-kinds.md +1 -1
  253. package/guides/typed-frontend.md +9 -0
  254. package/llms/client.md +54 -36
  255. package/llms/errors.md +26 -6
  256. package/llms/fields.md +53 -30
  257. package/llms/filters.md +55 -46
  258. package/llms/kinds-agent-mcp.md +10 -9
  259. package/llms/kinds-core.md +19 -15
  260. package/llms/kinds-knowledge.md +4 -4
  261. package/llms/kinds-realtime.md +25 -23
  262. package/llms/lambda.md +42 -30
  263. package/llms/legacy.md +6 -7
  264. package/llms/lock.md +21 -17
  265. package/llms/object-kinds.md +9 -11
  266. package/llms/statements-calls.md +41 -20
  267. package/llms/statements-catalog.md +78 -71
  268. package/llms/statements-data.md +35 -25
  269. package/llms/statements-runtime.md +28 -18
  270. package/llms/tests.md +20 -7
  271. package/llms/toolchain.md +12 -9
  272. package/llms/triggers.md +14 -18
  273. package/llms/values.md +16 -9
  274. package/llms-full.txt +689 -549
  275. package/llms.txt +120 -137
  276. package/manifest.json +228 -246
  277. package/package.json +1 -1
  278. package/skills/xano-backend/SKILL.md +10 -12
  279. package/types/lambda-globals.d.ts +6 -1
  280. package/dist/branch-commands-75IYFTBS.js +0 -80
  281. package/dist/codegen-command-JWOW6HE5.js +0 -182
  282. package/dist/env-example-refresh-4V2OCDJE.js +0 -135
  283. package/dist/init-command-UR5MSXIH.js +0 -142
  284. package/dist/promote-command-RURHOLNR.js +0 -148
  285. package/dist/pull-command-ITO76ENU.js +0 -170
  286. package/dist/release-command-CVGIUD4M.js +0 -152
  287. package/dist/routes-manifest-file-GYNYFKAH.js +0 -41
  288. package/dist/sync-baseline-BJDKG4F2.js +0 -38
  289. package/dist/update-check-O7QC5TBB.js +0 -140
  290. package/dist/xano-Z3SRHYOR.js +0 -43
@@ -10,36 +10,40 @@ to survive a rename).
10
10
 
11
11
  - `defineFunction({ name, guid?, description?, docs?, workspace?, input?, stack?, response?, tests? })`
12
12
  - `query({ name, verb, apiGroup?, guid?, auth?, input?, stack?, response?, responseType?, apiEnabled?, disabled?, cache?, description?, docs?, tests?, example? })` — a `cache` setting turns caching on unless `active: false`
13
- - `verb`: `"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD"` (required), UPPERCASE. Anything else — most often a lowercase `"post"` — makes `query()` THROW, because Xano does NOT reject it: it stores the verb as NULL, a null verb serves as GET, and the endpoint then answers on the wrong method while the one you meant 404s `Unable to locate request.`
13
+ - `verb`: `"GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD"` (required), UPPERCASE. Anything else (e.g. lowercase `"post"`) makes `query()` THROW — Xano would store NULL, a null verb serves as GET, and the verb you meant 404s `Unable to locate request.`
14
14
  - `apiGroup`: an `apiGroup()` def handle (or its name) — binds by guid, stable across syncs. Raw numeric `apiGroupId?` is the escape hatch and wins if both given.
15
- - `auth`: `false` (no auth) or an auth-table id; `responseType`: `"standard" | "stream"` (default `standard`) — any other spelling THROWS, since Xano stores an unrecognized one as NULL and a null buffers as `standard`, so a misspelled stream quietly does not stream.
15
+ - `auth`: `false` (no auth) or an auth-table id; `responseType`: `"standard" | "stream"` (default `standard`) — any other spelling THROWS (Xano would store NULL and buffer it as `standard`). ⚠ `s.api.stream` does nothing unless `responseType: "stream"`: in a `standard` query its chunk is SILENTLY DROPPED (no warning) and the normal `response` is served. Paired, each `s.api.stream({ value })` call emits ONE Server-Sent Event — the wire is `Content-Type: text/event-stream`, a `data: <json of value>` line per event, with an `id:` line that is a MILLISECOND TIMESTAMP and is NOT unique (ids repeat within a ms, so `Last-Event-ID` resume is unreliable). The query's own `response` is not sent in `stream` mode. Consumer recipe (`EventSource`/`fetch`): `llms/client.md`.
16
16
  - `name` is the endpoint PATH within the group.
17
17
  - A `{param}` segment is a URL PATH PARAM bound to the input of the same name, and segments chain: `name: "blog/{slug}/review/{review_id}"` + `input: { slug: input.text(), review_id: input.int() }`. Read it with `inp("slug")` like any other input.
18
- - Every `{param}` MUST have a matching input or `query()` THROWS — Xano treats an unbound marker as inert route text, so the endpoint would answer on the path and see nothing.
19
- - A `{param}` need NOT be a whole segment (`"blog/post-{slug}"` routes fine), but its type must fit one segment (no object/list/json/file/geo/vector); there are no wildcards or patterns. `required: true` is NOT demanded (the engine's editor leaves path inputs unmarked).
18
+ - Every `{param}` MUST have a matching input or `query()` THROWS — Xano would treat an unbound marker as literal route text.
19
+ - A `{param}` need NOT be a whole segment (`"blog/post-{slug}"` routes fine), but its type must fit one segment (no object/list/json/file/geo/vector); there are no wildcards or patterns. `required: true` is NOT demanded.
20
20
  - An input a `GET`/`DELETE`/`HEAD` looks ONE ROW up by (`s.db.get`/by-field edit/patch/delete; not `has` or an email/token/code) belongs in the path — `export()` warns `query.path-segment-candidate`: `getPath()` types STATIC. A segment is any value naming WHICH resource is wanted (`"shop/{country}"`); one that NARROWS A LIST (`s.db.query`) stays a query param. Intended? `diagnostics: { allow: [code] }` on the query (any def, for its own advisories) accepts it under `--strict`.
21
21
  - Routes are matched FIRST-FIT in creation order, and a literal gets NO precedence over a `{param}`: `"runs/{id}"` (a text `id`) created before `"runs/trend"` answers `GET /runs/trend` itself. Two routes in one group and verb that one request path can match are REFUSED at `export()` (`query.route-shadowed`) — reordering `registerQueries` cannot fix it, since a release keeps an existing route first. Make the paths disjoint (`"runs/by-id/{id}"`), or declare a numeric param `input.int({ required: true })` (or `decimal`): only a REQUIRED int/decimal segment matches digits only — an OPTIONAL one matches any text, so `input.int()` still takes `trend`.
22
22
  - Inputs absent from the path are ordinary query-string/body params.
23
- - Name charset is ONLY `A-Za-z0-9_-/{}`, max 200: a `.` (`"export.zip"`) is NOT rejected by Xano — it stores an EMPTY name that deploys clean then 404s forever, so `query()` THROWS. Use `"export_zip"` and set the extension in the response headers.
23
+ - Name charset is ONLY `A-Za-z0-9_-/{}`, max 200: a `.` (`"export.zip"`) THROWS — Xano would store an EMPTY name that deploys clean then 404s. Use `"export_zip"` and set the extension in the response headers.
24
24
  - **Client recipe:** `q.getPath({ params: { slug: "hello" } })` → `/api:<canonical>/blog/hello` — never interpolate by hand.
25
25
  - `getPath` percent-encodes each value (so `?`/`#`/spaces stay in their segment) and throws on what encoding cannot contain: a `/`, and a segment that becomes `.`/`..` as sent (a URL parser drops those before routing, addressing a different endpoint).
26
26
  - The keys are typed from the literal `name`, so a typo is a compile error.
27
27
  - `q.toSearchParams(input)` drops GET path params (free `query.toSearchParams` keeps them); lists send `k[]=a&k[]=b` (`k=a&k=b` binds only `b`).
28
28
  - Browser bundle cost, the `routes.gen.ts` alternative (paths and request types), and spot-checking a def from Node: `llms/client.md`.
29
29
  - `apiGroup({ name, guid?, canonical?, description?, docs?, swagger?, apiGroupEnabled?, documentation?, cors?, middleware? })` — a query container; queries bind to it via their `apiGroup`. `canonical` holds only letters, digits, `_` and `-` (it is the `<canonical>` of `/api:<canonical>`); anything else THROWS at build.
30
- - `documentation?`: `{ require_token? }` — the gate on this group's hosted docs. `require_token: true` IS the declaration; the token lives in `xano/.secrets.json` under this group's guid, and a literal `token` FAILS the export. ⚠ ALWAYS emitted, present or not: an absent key is written as the engine default on import, so omitting the block CLEARS an existing gate (the opposite of the `workspaceConfig` rule). `swagger: true` publishes the docs; `require_token` gates them only alongside a non-empty token, so `swagger: true` with no gate makes the whole group readable by anyone with the URL — export warns once per build and `--strict` fails; `diagnostics: { allow: ["api-group.docs-public"] }` accepts it. A declared gate with NO token drops the block, so those bytes clear it: export FAILS under `swagger: true`, and with `swagger` off warns and completes.
30
+ - `documentation?`: `{ require_token? }` — the gate on this group's hosted docs; `swagger: true` publishes the docs. `require_token: true` IS the declaration; the token lives in `xano/.secrets.json` under this group's guid.
31
+ - The block is ALWAYS emitted: an absent key is written as the engine default on import, so omitting it CLEARS an existing gate (the opposite of the `workspaceConfig` rule).
32
+ - ⚠ `require_token` gates them only alongside a non-empty token: `swagger: true` with no gate makes the whole group readable by anyone with the URL — export warns once per build and `--strict` fails; `diagnostics: { allow: ["api-group.docs-public"] }` accepts it.
33
+ - A declared gate with NO token drops the block, clearing the gate: export FAILS under `swagger: true`, and with `swagger` off warns and completes.
34
+ - A literal `token` FAILS the export.
31
35
  - `cors?`: `{ mode?, allowOrigins?: string[], allowHeaders?: string[], allowCredentials?, maxAge?, allowMethods?: { get?, post?, put?, patch?, delete?, head? } }`.
32
- - `mode?`: `"default"` (the default) | `"custom"` | `"disabled"`, lowercase — a fourth value THROWS at export (`apiGroup()` itself does not check), because Xano neither rejects nor blanks it: it DROPS THE WHOLE API GROUP on import, so the deploy succeeds and every query in the group 404s. ⚠ Every OTHER field applies only under `"custom"`: `"default"` serves a FIXED permissive policy (any origin, `allow-headers: *`, `allow-credentials: true`, `max-age: 86400`) and ignores the block, so setting `maxAge`/`allowCredentials`/`allowHeaders` alone changes nothing. `"disabled"` sends no CORS headers at all, so every browser call fails.
36
+ - `mode?`: `"default"` (the default) | `"custom"` | `"disabled"`, lowercase — a fourth value THROWS at export (`apiGroup()` itself does not check); otherwise Xano DROPS THE WHOLE API GROUP on import (deploy succeeds, every query 404s). ⚠ Every OTHER field applies only under `"custom"`: `"default"` serves a FIXED permissive policy (any origin, `allow-headers: *`, `allow-credentials: true`, `max-age: 86400`) and ignores the block, so setting `maxAge`/`allowCredentials`/`allowHeaders` alone changes nothing. `"disabled"` sends no CORS headers at all, so every browser call fails.
33
37
  - ⚠ Under `"custom"`, `allowOrigins` is matched as EXACT strings (scheme+host+port, no wildcard or subdomain expansion) and `"*"` is compared as a literal origin — it matches NOTHING. An unmatched origin gets no `access-control-*` headers at all, so the browser call fails while export, deploy and the preflight look fine. Name each origin, or use `mode: "default"` for any-origin. `allowMethods` gates the REAL response too: a verb left off gets no CORS headers back even though its preflight passes. Export warns on an empty origin list, a `"*"` entry, and a policy with no method enabled; a non-origin entry (trailing `/`, path) is refused.
34
38
  - Tasks, workflow tests, middleware and tools below (agents and MCP servers: `llms/kinds-agent-mcp.md`) share the envelope conventions (`guid?`, `description?`, `docs?`, `tags?`, `history?`) unless noted.
35
39
  - `task({ name, guid?, description?, docs?, datasource?, active?, tags?, history?, schedule?, stack?, middleware? })` — a scheduled background job (function-like `stack`, no `input`/`response`). `active?` defaults `true`; `active: false` deploys it parked.
36
- - `schedule?`: a `ScheduleDef[]` (NOT a single object) — `{ startsOn, freq?, repeatEnabled?, endsOn?, endsEnabled? }`. `startsOn`/`endsOn` are **timestamp strings** validated at encode time — `"2026-01-01T00:00:00Z"`, or the space-separated `"2026-01-01 00:00:00+0000"` a pulled workspace carries — never epoch numbers, and never zoneless; `freq` is the repeat interval **in SECONDS** (omitted ⇒ runs ONCE) — spell it `every("15m")`, a compile-time duration-to-seconds helper (`s`/`m`/`h`/`d`/`w`, terms concatenate). No cron, no timezone — a fixed-offset `startsOn` drifts an hour at each DST change; for a local time run hourly, gated on the local hour `withFilters(c.now(), fl.epochms_date("G", "America/New_York"))`. `repeatEnabled?`/`endsEnabled?` follow whether `freq`/`endsOn` is set and are recovery-only — state one to reproduce a stored gate left OFF. Fires on an ephemeral (see Gotchas).
37
- - `workflowTest({ name, guid?, description?, docs?, datasource?, active?, tags?, stack? })` — an end-to-end test. NO `input`/`response`: `.call` something with an `as`, then assert on that var — `s.function.call({ fn, input, as: "r" })`, `s.expect.to_equal({ expr: ref("r"), value: c.int(42) })`. `s.expect.*` belongs here — it is not inert elsewhere (a failure 500s the request), so treat one in a query/function/task as a mistake to remove. `active?` defaults `true`; chain tests with `s.workflow_test.call({ workflowTest: <def handle> })`.
38
- - `datasource?`: Default `""` is an EMPTY datasource (recommended), not "no datasource". Any non-empty name makes the engine CLONE it before EVERY run — against production-sized data, slow enough to fail the run, which is why `"live"` warns at compile time. On an EPHEMERAL, `"live"` holds only the seed fixtures (plus rows a `--keep-data` deploy kept), so it is the way to read `table({ seed })` rows — a small clone, dropped after the run. ⚠ The value is STORED, so clear it before you promote or the same test clones the real database.
40
+ - `schedule?`: a `ScheduleDef[]` (NOT a single object) — `{ startsOn, freq?, repeatEnabled?, endsOn?, endsEnabled? }`. `startsOn`/`endsOn` are **timestamp strings** validated at encode time — `"2026-01-01T00:00:00Z"`, or the space-separated `"2026-01-01 00:00:00+0000"` a pulled workspace carries — never epoch numbers, and never zoneless; `freq` is the repeat interval **in SECONDS** (omitted ⇒ runs ONCE) — spell it `every("15m")`, a compile-time duration-to-seconds helper (`s`/`m`/`h`/`d`/`w`, terms concatenate). No cron, no timezone — a fixed-offset `startsOn` drifts an hour at each DST change; for a local time run hourly, gated on the local hour `withFilters(c.now(), fl.epochms_date("G", "America/New_York"))`. `repeatEnabled?`/`endsEnabled?` follow whether `freq`/`endsOn` is set and are recovery-only — state one to reproduce a stored gate left OFF. Runs on every deploy target (`llms.txt` Gotchas).
41
+ - `workflowTest({ name, guid?, description?, docs?, datasource?, active?, tags?, stack? })` — an end-to-end test. NO `input`/`response`: `.call` something with an `as`, then assert on that var — `s.function.call({ fn, input, as: "r" })`, `s.expect.to_equal({ expr: ref("r"), value: c.int(42) })`. `s.expect.*` belongs here — it is not inert elsewhere (a failure 500s the request), so treat one in a query/function/task as a mistake to remove. `active?` defaults `true`; `active: false` parks the test — `test run-all`/`deploy --test` SKIP it (reported `status: "skipped"`, never failing the suite), `test list` shows it `inactive`, and `test run "<name>"` still runs it. Chain tests with `s.workflow_test.call({ workflowTest: <def handle>, as: "child" })` then `s.expect.to_be_null({ expr: ref("child") })`, or a failing child passes the parent.
42
+ - `datasource?`: Default `""` is an EMPTY datasource (recommended), not "no datasource". Any non-empty name is CLONED before EVERY run — against production-sized data, slow enough to fail the run; `"live"` warns at compile time. On an EPHEMERAL, `"live"` holds only the seed fixtures (plus rows a `--keep-data` deploy kept): the way to read `table({ seed })` rows — a small clone, dropped after the run. ⚠ The value is STORED, so clear it before you promote or the same test clones the real database.
39
43
  - `middleware({ name, guid?, description?, docs?, resultStrategy?, exceptionPolicy?, tags?, history?, input?, stack?, response?, responseShape?, tests? })` — a pre/post interceptor (function-like `stack`); attach it via a host's `middleware: { pre, post }`. ⚠ `input` ENCODES but an ATTACHED middleware never has it bound — the host request binds its own inputs, so `inp()` inside pre/post fails at runtime with `Unable to locate input` and a declared default does not stand in (`export()` warns). Read the request body with `s.util.get_all_input` instead; it yields a `{ type, vars }` envelope whose `vars` DIFFERS BY PHASE: `pre` → the request inputs (`payload.vars.<field>`); `post` → `{ status, result }`, the host's outcome (`payload.vars.result.<field>`; plus `payload` on an error). A request field read in `post` 500s after the host already ran (`export()` warns); read the request there with `s.util.get_raw_input`. `s.middleware.call` is the one path that DOES bind the declared map.
40
- - `resultStrategy?`: `"merge" | "replace"` (default `merge`) — how the middleware `response` folds into the accumulator of the phase it is ATTACHED to, and the two phases accumulate DIFFERENT things. In `post` the accumulator is the host's RESULT, so a returned object changes what the CALLER receives. In `pre` it is the host's REQUEST INPUTS, so a returned object changes what the HOST receives. `merge` folds key-by-key, `replace` substitutes wholesale; either way the next entry in the chain sees the updated value. So `pre` + `replace` DISCARDS every caller input the middleware does not re-emit, and a discarded input is then unreadable — a 500, even where it is declared `required: false`, because input defaulting has already happened by the time the override lands.
41
- - `exceptionPolicy?`: `"silent" | "rethrow" | "critical"` (default `"rethrow"` — a throw ABORTS the request and surfaces the authored error/status, which is what a guard wants). `"silent"` swallows the throw and lets the request through, so a guard set to it is NOT enforced — use it only for advisory middleware. `"critical"` is `"rethrow"` plus skipping the `post` chain.
42
- - `tool({ name, guid?, description?, instructions?, docs?, enabled?, title?, annotations?, icons?, output?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — a function-like operation (`input`/`stack`/`response`) that a toolset (MCP server or agent) exposes. Register it, then reference it from a toolset's `tools`. `title`/`annotations`/`icons`/`output` are MCP metadata (`llms/kinds-agent-mcp.md`).
44
+ - `resultStrategy?`: `"merge" | "replace"` (default `merge`) — how the middleware `response` folds into its phase's accumulator: in `post` the host's RESULT (changes what the CALLER receives), in `pre` the host's REQUEST INPUTS (changes what the HOST receives). `merge` folds key-by-key, `replace` substitutes wholesale; the next entry in the chain sees the updated value. `pre` + `replace` DISCARDS every caller input the middleware does not re-emit; reading a discarded input 500s, even one declared `required: false` (defaulting already ran).
45
+ - `exceptionPolicy?`: `"silent" | "rethrow" | "critical"` (default `"rethrow"` — a throw ABORTS the request and surfaces the authored error/status). `"silent"` swallows the throw and admits the request; never use it on a guard. `"critical"` is `"rethrow"` plus skipping the `post` chain.
46
+ - `tool({ name, guid?, description?, instructions?, docs?, enabled?, title?, annotations?, icons?, output?, tags?, history?, input?, stack?, response?, responseShape?, middleware? })` — a function-like operation (`input`/`stack`/`response`) that a toolset (MCP server or agent) exposes. Register it, then reference it from a toolset's `tools`. Name charset as a query's (`A-Za-z0-9_-/{}`, max 200). `instructions` is the description the MODEL/client sees (MCP `description`, agent-tool description) and what a connection trigger rewrites; it REPLACES `description`, which shows only when `instructions` is empty (both set warns `tool.description-shadowed`). `title`/`annotations`/`icons`/`output` are MCP metadata (`llms/kinds-agent-mcp.md`).
43
47
  - An addon is a single table-bound db query, NOT a statement stack: `addon({ name, table, tableAlias?, where?, sort?, output: [cols], cardinality?: "single"|"list"|"count"|"exists"|"aggregate", group?, eval?, input?, context? })`, registered via `registerAddons([...])`.
44
48
  - `table` auto-fills the `context.dbo` binding. ⚠ Never author `table: null` — that is a BROKEN table-less addon returning nothing; `codegen` emits it only for an already-broken pulled object.
45
49
  - `tableAlias` is its SQL alias (`context.dbo.as`), qualifying `where`/`sort` columns (`col("merchant.id")`).
@@ -67,7 +71,7 @@ response-bearing triggers) maps to the stored `result[]`:
67
71
  surface — `s.conditional`/`s.while` `when` (incl. each `elif` branch), and
68
72
  `db.query` `where`/`additionalWhere` (and the search triggers) — one shared tree.
69
73
 
70
- - `op`: `=`, `!=`, `>`, `<`, `>=`, `<=` (JS aliases `==` `===` `!==` are accepted and normalized).
74
+ - `op`: `=`/`==`/`!=` LOOSE (`null = 0` holds); `===`/`!==` STRICT; `>` `<` `>=` `<=`. Null check: `cond.isNull`.
71
75
  - `left`/`right` are `Value`s — `col("x")` (a table column, `db.*` statements only), `ref`, `inp`, `auth(...)`, or `c.*`.
72
76
  - For the full operator set (`in`/`like`/`ilike`/`between`/`contains`/`overlaps`/`@>`/`~`/`search`/…)
73
77
  use `cmp(left, op, right, { ignoreEmpty? })`; compose nested boolean logic with `and(...)`/`or(...)`.
@@ -81,7 +85,7 @@ surface — `s.conditional`/`s.while` `when` (incl. each `elif` branch), and
81
85
  `empty`/`notEmpty`, `isNull`/`notNull`, `between(v, lo, hi)`, `has(obj, path)`, `count(v, n)`.
82
86
  Each returns a `Comparison`, usable anywhere `expr(...)` is.
83
87
  - A condition/`where` accepts a single `expr(...)`/`cmp(...)`, an `and()`/`or()` group, an array of
84
- those (ANDed), or (for `where`) a raw `Value`. `s.conditional`/`s.while`/`s.switch`, `db.query`,
88
+ those (ANDed). `s.conditional`/`s.while`/`s.switch`, `db.query`,
85
89
  `precondition`, and the `array.*` predicates all take the same TREE shape (operators per above).
86
90
  - ⚠ `mixed(a, { or: b }, { and: c })` reproduces a container whose terms do NOT all join the
87
91
  same way — pulled workspaces contain it. **Do not author it** (export warns `condition.mixed`). The
@@ -2,8 +2,8 @@
2
2
 
3
3
  > Read when the workspace defines a `knowledge()` item.
4
4
 
5
- - `knowledge({ name, description?, type?, mode?, enabled?, body, refs?, guid?, tags? })` — markdown shared by every AI that builds the backend: Xano's own AI reads it before it acts — the workspace's builder agent, and outside agents reading the workspace through the Meta API or MCP — and a local coding agent reads the same `.md` files in the repo; deploy and `pull` keep the copies in sync. It does NOT reach an `agent()` run by `s.ai.agent.run`, whatever its `type` or `mode`: put what such an agent must know in its `llm.systemPrompt`. Takes `registerKnowledge`.
6
- - `body` (REQUIRED): `knowledgeFile("./runbook.md", import.meta.url)` — a path to a real markdown FILE. There is no inline-string form. The path resolves relative to the MODULE THAT DECLARES the item, not the process working directory and not the workspace entry; `import.meta.url` is required and is what makes that true.
5
+ - `knowledge({ name, description?, type?, mode?, enabled?, body, refs?, guid?, tags? })` — markdown shared by every AI that builds the backend. Xano's own AI reads it before it acts: the workspace's builder agent, and outside agents reading the workspace through the Meta API or MCP. A local coding agent reads the same `.md` files in the repo; deploy and `pull` keep the copies in sync. It does NOT reach an `agent()` run by `s.ai.agent.run`, whatever its `type` or `mode`: put what such an agent must know in its `llm.systemPrompt`. Takes `registerKnowledge`.
6
+ - `body` (REQUIRED): `knowledgeFile("./runbook.md", import.meta.url)` — a path to a real markdown FILE. There is no inline-string form. The path resolves relative to the MODULE THAT DECLARES the item (not the working directory or the workspace entry), via the required `import.meta.url`.
7
7
  - `refs?`: `knowledgeDir("./runbook", import.meta.url)` — a directory whose WHOLE tree ships, recursively, paths preserved: UTF-8 text only (else refused; binary `.DS_Store` skipped), symlinks not followed. Keep the body OUT of it, or it ships as a reference file.
8
8
  - `type?`: `"skill"` (default) | `"doc"` | `"agents.md"`. `skill` and `doc` differ in how they are filed, not in what an agent receives.
9
9
  - `mode?`: `"auto"` (default) | `"always"` | `"referenced"`.
@@ -16,5 +16,5 @@
16
16
  - `mode: "referenced"` — full body only on turns whose message names the item (bare name or `@name`).
17
17
  - `mode: "auto"` — name and `description` only; the agent loads the body when a request matches.
18
18
  - Reference files are never injected wholesale — an agent searches them on demand. That is what makes a large `mode: "auto"` item cheap.
19
- - ⚠ `mode: "always"` on a long body spends its whole length on every request, and nothing in the types says so. `"auto"` is the default for that reason. For an `auto` item `description` is ALL the agent sees until it decides to load the body, so write it to be matched against a request rather than as a title.
20
- - `name` takes letters, digits, and `/ _ - { } . ` or a space; anything else is an export error.
19
+ - ⚠ `mode: "always"` costs the full body on every request (nothing in the types flags it). For an `auto` item `description` is ALL the agent sees until it decides to load the body, so write it to be matched against a request rather than as a title.
20
+ - `name` takes letters, digits, space, and `/` `_` `-` `{` `}` `.`; anything else is an export error.
@@ -7,13 +7,13 @@
7
7
  - `enabled` defaults to **false** — the one `enabled` in the SDK that does.
8
8
  - An enabled server with no active channel still refuses the handshake.
9
9
  - `realtimeChannel({ name, server, guid?, description?, active?, input?, anonymousClients?, presence?, publish?, conversation?, delivery?, rateLimit?, tags?, history?, middleware? })`
10
- - `name` is a PATH (`"lobby"`, `"rooms/{room_id}"`); `input` types its `{param}` segments, NOT the payload. Every `{param}` MUST have a matching input, and that input must be a SCALAR and not a list (`json`/`object`/`array: true` have no URL form), or `realtimeChannel()` THROWS. `required: true` is NOT checked and is not needed — segment counts must match, so the segment is always present at join. Name charset as query (`A-Za-z0-9_-/{}`, max 200), and so is `tool`; `realtimeMessage` is NARROWER — no `/` or `{}`.
10
+ - `name` is a PATH (`"lobby"`, `"rooms/{room_id}"`); `input` types its `{param}` segments, NOT the payload. Every `{param}` MUST have a matching input, and that input must be a SCALAR and not a list (`json`/`object`/`array: true` have no URL form), or `realtimeChannel()` THROWS. `required: true` is NOT checked and not needed (segment counts must match, so the segment is always present at join). Name charset as query (`A-Za-z0-9_-/{}`, max 200); `realtimeMessage` is narrower — no `/` or `{}`.
11
11
  - Matching is STRICT: a literal segment beats a param (`rooms/lobby` and `rooms/{room_id}` coexist); segment counts must be EQUAL (`rooms/{room_id}` does NOT match `rooms/42/edit`); literals are CASE-SENSITIVE; an empty segment is REJECTED, not collapsed (a leading/trailing/doubled `/` matches nothing). `realtimeChannel()` refuses it and a partial-segment `{param}`; `getChannel()` a value outside `[A-Za-z0-9_-]`.
12
12
  - An INACTIVE channel reports the same error as a nonexistent one — deactivating leaks nothing.
13
- - `middleware?: { pre?, post? }` is the CONTAINER tier, on the channel and on the server alike — the default chain every message inherits, the same shape an api group has. Full chain: message -> channel -> server -> branch/workspace, mirroring `history`. Put a realtime auth or rate-limit guard here rather than repeating it on every `realtimeMessage`.
13
+ - `middleware?: { pre?, post? }` is the CONTAINER tier, on the channel and on the server alike — the default chain every message inherits, the same shape an api group has. Full chain: message -> channel -> server -> branch/workspace, mirroring `history`. ⚠ It cannot GUARD: a middleware that throws fails open (below).
14
14
  - `anonymousClients` also gates CONNECT: a tokenless socket connects only if an active channel of its server sets it (no server flag); each channel admits its own join.
15
15
  - `publish?: { who?: "nobody"|"anyone"|"authenticated", direct? }` — `who` defaults to `nobody`: nobody can publish until you set it. `direct` (default false) allows DIRECT messages — a frame whose `options.to = { dbo_id, row_id }` addresses one USER (`dbo_id` = the auth table's id as `s.realtime.get_session` reports it, `row_id` = the user's row id) and reaches every socket of theirs on the channel, no one else; the sender gets a receipt `{ delivered_local, direct: true }`. `direct` REPLACES `who` for such a frame rather than adding to it (`direct: true` with `who: "nobody"` delivers direct messages and refuses broadcasts); an anonymous sender is refused. A direct message is never stored in the transcript or the `at_least_once` stream, so an offline user never gets it. ⚠ An `options.to` naming no usable identity is sent as an ordinary broadcast to the whole channel where `who` admits the sender.
16
- - `conversation?: { enabled?, limit?, ttl? }` — the client-visible TRANSCRIPT replayed to a joiner (distinct from `history`, which is execution history). ⚠ `limit` DEFAULTS TO 0 AND 0 MEANS OFF: `{ enabled: true }` alone records nothing and replays nothing, silently. `ttl` is an IDLE expiry of the WHOLE transcript, refreshed by every write (an active channel never ages out; a silent one loses all of it at once) — NOT a per-message age cap.
16
+ - `conversation?: { enabled?, limit?, ttl? }` — the client-visible TRANSCRIPT replayed to a joiner (distinct from `history`, which is execution history). ⚠ `limit` DEFAULTS TO 0 AND 0 MEANS OFF: `{ enabled: true }` alone records nothing and replays nothing, silently — always pass `limit`. `ttl` is an IDLE expiry of the WHOLE transcript, refreshed by every write (an active channel never ages out; a silent one loses all of it at once) — NOT a per-message age cap.
17
17
  - `delivery?: { guarantee?: "at_most_once"|"at_least_once", perRecipient? }` — `perRecipient` is independent of the guarantee, is a NO-OP unless the channel declares a `deliver` trigger, and costs a stack PER RECIPIENT PER MESSAGE. Per-viewer redaction needs BOTH HALVES — this flag AND an active `deliver` trigger bound to the channel — and with either missing the payload is delivered UNCHANGED to everyone; `export()` warns on each half alone.
18
18
  - `rateLimit?: { messagesPerMinute? }` — 0 = unlimited, checked BEFORE the handler runs. A COST guardrail, not a security control: an anonymous client is bucketed per CONNECTION (reconnecting resets it), and it fails OPEN when its store is down.
19
19
  - `realtimeMessage({ name, channel, server?, guid?, description?, active?, auth?, deliverTo?, input?, middleware?, stack?, response?, responseShape?, history?, disabled?, tags? })` — the invocable unit (the realtime analogue of a query).
@@ -23,54 +23,56 @@
23
23
  - **Both input surfaces read as ordinary inputs:** `inp("body")` for a payload field, `inp("room_id")` for the channel's `{room_id}`. No session lookup, no frame parsing.
24
24
  - A path param is bound ONCE at join and read from the connection thereafter, never from the frame — a sender cannot claim a room it did not join.
25
25
  - `s.realtime.get_session({ as })` — the CALLER's realtime session for the current frame. FLAT shape:
26
- - `authenticated` bool · `client_id` text (the AUTHED ROW ID as text, `""` anonymous) · `dbo_id` int (the auth TABLE's id — NOT the user's row id; `0` anonymous — to look the caller up use `client_id`. `dbo_id` is an int in the same position and typechecks, so a gate that keys on it finds no user and refuses EVERYONE) · `socket_id` int (transport id) · `channel` text (resolved path, `""` in a server trigger) · `params` object (bound path params, `{}` when none — `ref("session.params.room_id")`) · `extras` object · `opened_at` decimal.
26
+ - `authenticated` bool · `client_id` text (the AUTHED ROW ID as text, `""` anonymous) · `dbo_id` int (the auth TABLE's id, `0` anonymous) · `socket_id` int (transport id) · `channel` text (resolved path, `""` in a server trigger) · `params` object (bound path params, `{}` when none — `ref("session.params.room_id")`) · `extras` object · `opened_at` decimal · `token_error` text|null (`"expired"`/`"invalid"` when the client SENT a token that did not authenticate — it connected anonymously; `null` otherwise).
27
+ - `dbo_id` is NOT the user's row id — look the caller up by `client_id`. A gate keyed on `dbo_id` typechecks, finds no user, and refuses EVERYONE.
27
28
  - Works in a realtime MESSAGE stack and in CHANNEL and SERVER trigger stacks; off that path it degrades to an anonymous session.
28
29
  - For a path param prefer `inp("room_id")` in a MESSAGE; a lifecycle TRIGGER has only the session. Reach for the session when you need the CONNECTION (identity/extras) — "who is this sender" on an anonymous-client channel.
29
- - ⚠ THREE UNRELATED THINGS ARE CALLED A CLIENT ID: `session.client_id` (app-facing identity), `session.socket_id` (transport), and a frame's `options.client_id` (the at_least_once CURSOR handle). Conflating the first and last breaks at_least_once for anonymous clients.
30
+ - Three unrelated things are called a client id: `session.client_id` (app-facing identity), `session.socket_id` (transport), and a frame's `options.client_id` (the at_least_once cursor handle). Conflating the first and last breaks at_least_once for anonymous clients.
30
31
  - `s.realtime.publish({ server, channel, data, message?, authTable?, authId? })` — the PUSH direction: originate a server-authored event onto a channel from ANY stack, no client frame first.
31
32
  - `server` is the handle or its NAME (resolved by name, not guid); `channel` is the FILLED-IN path (`channel.getChannel({ room_id: 42 })`), never the template — a constant still carrying `{param}` THROWS at author time, and a constant `server`/`channel` naming nothing this workspace registers WARNS at export.
32
33
  - A PER-ROW path whose id is only known at runtime is built as a value, not with `getChannel()` (which needs the id at author time): `withFilters(c.text("rooms/"), fl.concat(ref("room.id")))`, or `s.set_var` + `s.text.prepend`. A computed `channel`/`server` — a `ref`/`inp`, or a constant carrying a filter chain — is left alone by the export check.
33
34
  - DELIVERY-ONLY — fanned out as-is; does NOT invoke a `realtimeMessage()` handler even when `message` names one (a channel `deliver` trigger still runs).
34
35
  - SERVER-AUTHORITATIVE — bypasses `publish.who`, which governs CLIENTS. Authorize in your own stack.
35
36
  - ⚠ FAIL-SOFT — a missing/disabled server or dead bus is swallowed engine-side, so a mis-targeted publish is SILENT with no result to check.
36
- - `authTable`/`authId` are ASSERTED attribution on the frame — not a credential, nothing validates them.
37
+ - `authTable`/`authId` are ASSERTED attribution on the frame — not a credential, nothing validates them. They land in `_meta.as`, NOT in `payload`.
38
+ - `s.realtime.kick({ server, channel, authTable, authId, reason? })` — remove one user from one channel: every socket of `authTable`/`authId` (the identity is REQUIRED) leaves the FILLED-IN `channel` path, on every node, through the same steps as a client `leave` (the `leave` trigger, a `presence_leave`), and receives `{ action: "leave", channel, payload: { left: true, kicked: true, reason } }`. The socket stays CONNECTED and keeps its other channels. Call it wherever you revoke a membership the `join` gate admitted.
39
+ - NOT fail-soft (unlike `publish`): an unknown server, a missing identity, or a dead bus FAILS the stack — a kick that silently did nothing would leave the member subscribed.
37
40
  - **Client recipe (derive, never hardcode):**
38
41
  - `server.getUrl(baseUrl)` → `wss://<host>/ws/<canonical>` — accepts the `https://…` instance base URL and normalizes the scheme. `channel.getChannel({ room_id: 42 })` → `"rooms/42"`, the path that goes in a frame's `channel` field. Both throw rather than guess. A canonical is minted by `npx @xano/sdk export <entry> --lock`.
39
- - Auth is a bearer token passed as the websocket SUBPROTOCOL: `new WebSocket(url, token)`. No token = an anonymous client, admitted only where `anonymousClients: true`.
42
+ - Auth is a bearer token passed as the websocket SUBPROTOCOL: `new WebSocket(url, token)`. No token = an anonymous client, admitted only where `anonymousClients: true`. ⚠ An INVALID, tampered, or EXPIRED token still connects — ANONYMOUSLY, with no error and no close (presence lists it `authenticated: false`) — and says why: `session.token_error` is `"expired"` or `"invalid"`, and a refusal the socket meets for being anonymous names the token: `{ message: "Your token has expired. Reconnect with a fresh token.", token_error: "expired", reason: "Anonymous clients cannot join this channel" }`. On an error frame carrying `token_error`, refresh the token and reconnect. For a hard refusal at connect, gate with a `realtimeServerTrigger` `connect` (`allowed: session.token_error == null`, or `session.authenticated` → a 4401 close).
40
43
  - Frames are JSON `{ action: "join"|"leave"|"broadcast"|"ack"|"ping"|"presence", channel, type?, payload?, options?, id? }`. `broadcast` REQUIRES `type`: a `realtimeMessage` of that channel, else refused `Unknown message type`. You must `join` before you may `broadcast`, and the server's context is ready only a moment after `open` — an immediate first frame is refused.
41
44
  - `options` is `{ to?, client_id?, channel? }` — `to: { dbo_id, row_id }` makes the frame a direct message (needs `publish.direct`), `client_id` is the at-least-once cursor handle, and `options.channel` WINS over a top-level `channel`.
42
45
  - ⚠ KEEP THE SOCKET ALIVE: an idle connection is REAPED after ~10 minutes. A LISTEN-ONLY client (a feed or dashboard that joins and rarely publishes) MUST send `{ action: "ping" }` (answered `pong`) or any frame periodically or it silently drops.
43
- - Server frames: `join` (ack `{ joined: true, params }`, + `cursor`/`resumed` on at_least_once) · `message` · `replay` · `broadcast` · `presence_full`|`presence_join`|`presence_leave` · `conversation_start`|`conversation_end` (replayed frames flagged `conversation: true`) · `pong` · `ack` · `error`.
44
- - ⚠ `broadcast` is a RECEIPT to the sender, not a delivery confirmation: `payload.delivered_local` counts recipients on the ANSWERING NODE ONLY, not the channel. It also carries `id` on at_least_once and `dropped: true` when the handler returned null.
45
- - `error` carries `payload.message`, plus `code`/`limit`/`retry_after` when rate limited. `rate_limited` is the ONLY code — do NOT switch on `code`.
46
+ - Server frames: `join` (ack `{ joined: true, params }`, + `cursor`/`resumed` on at_least_once) · `message` · `replay` · `broadcast` · `presence_full`|`presence_join`|`presence_leave` · `conversation_start`|`conversation_end` (replayed frames flagged `conversation: true`) · `pong` · `ack` · `error`. An `s.realtime.publish` frame also carries `_meta`: `{ injected: true }` (asserted marker for a server-authored event vs a relayed peer), plus `as: { dbo_id, row_id }` from `authTable`/`authId`.
47
+ - `broadcast` is a RECEIPT to the sender, not a delivery confirmation: `payload.delivered_local` counts recipients on the ANSWERING NODE ONLY, not the channel. It also carries `id` on at_least_once and `dropped: true` when the handler returned null.
48
+ - `error` carries `payload.message`, plus `code`/`limit`/`retry_after` when rate limited. `rate_limited` is the only code — do not switch on `code`.
46
49
  - An `error` is a per-frame refusal, NOT a disconnect — EXCEPT a failed handshake and a REFUSED `connect` trigger, which each send one and then CLOSE with code 4401.
47
- - **Tenant instances (isolated DB):** a tenant's realtime objects live in the TENANT's database, so BOTH halves of a client must name the tenant.
48
- - Socket: `server.getUrl(base, { tenant })` → `/ws/<tenant>:<canonical>`. ⚠ A bare canonical on a tenant host resolves against the INSTANCE workspace instead.
49
- - That colon form is PECULIAR TO THE SOCKET. Every other tenant URL gives the tenant its OWN segment — the HTTP half of the same client is `https://<host>/tenant/<tenant>/api:<canonical>/…`. NO request header is required for either.
50
- - Because the shapes differ, `getUrl` TRANSLATES a tenant base URL instead of concatenating: pass the `https://<host>/tenant/<name>` that `npx @xano/sdk status` prints (and that deploy injects as `window.XANO_HOST`) and the tenant is LIFTED into the socket form. So `getUrl(window.XANO_HOST)` needs no `{ tenant }`, and a CONFLICTING `{ tenant }` alongside it throws.
51
- - ⚠ `getUrl`/`socketUrl` are NOT idempotent — a `baseUrl` that already carries a `/ws/<…>` path THROWS. Resolve ONCE from the http(s) base; never feed a result back in.
50
+ - **Tenant instances (isolated DB):** a tenant's realtime objects live in the TENANT's database, so both the socket and the HTTP half of a client must name the tenant. No request header is required for either.
51
+ - Socket: `server.getUrl(base, { tenant })` → `/ws/<tenant>:<canonical>` — the colon form is socket-only; HTTP gives the tenant its own segment (`https://<host>/tenant/<tenant>/api:<canonical>/…`). ⚠ A bare canonical on a tenant host resolves against the INSTANCE workspace instead.
52
+ - `getUrl` TRANSLATES a tenant base URL: pass the `https://<host>/tenant/<name>` that `npx @xano/sdk status` prints (and deploy injects as `window.XANO_HOST`) and the tenant is LIFTED into the socket form, so `getUrl(window.XANO_HOST)` needs no `{ tenant }`; a conflicting `{ tenant }` alongside it throws.
53
+ - `getUrl`/`socketUrl` are NOT idempotent — a `baseUrl` that already carries a `/ws/<…>` path THROWS. Resolve ONCE from the http(s) base; never feed a result back in.
52
54
  - Still pass `{ tenant }` explicitly for a tenant on its OWN DOMAIN — the hostname carries it for HTTP, but there is nothing in the URL for the socket to lift.
53
- - ⚠ Tokens are tenant-scoped (audience `<tenant>:<license>`, not the bare license), so one minted through the instance workspace is REJECTED by a tenant's realtime server — authenticate and dial through the same tenant.
55
+ - Tokens are tenant-scoped (audience `<tenant>:<license>`, not the bare license), so one minted through the instance workspace is REJECTED by a tenant's realtime server — authenticate and dial through the same tenant.
54
56
  - **Presence frames** (a `presence: true` channel only):
55
- - `presence_full` carries `payload.members`, an ARRAY: at join it EXCLUDES the receiver (first joiner: `[]`), on a re-request it includes it. `presence_join`/`presence_leave` carry a single `payload.member`.
57
+ - `presence_full` carries `payload.members`, an ARRAY: it INCLUDES the receiver, at join (first joiner: itself) and on a re-request. `presence_join`/`presence_leave` carry a single `payload.member`. `members` is in NO guaranteed order (not join order): sort it yourself if order matters.
56
58
  - A member is `{ id, dbo_id, authenticated, extras, joined_at }`: `id` the auth row id as a string (`"0"` anonymous), `dbo_id` the auth table's id (`0` anonymous), `extras` the connection's extras (`[]` if none), `joined_at` epoch SECONDS.
57
59
  - Render `presence_full`, then apply deltas. One member per authenticated identity (a second tab fires no `presence_join`); anonymous ones all have `id` `"0"`, never collapsed.
58
60
  - Join order: `join` ack → `presence_full` → (others get `presence_join`) → conversation replay → `replay` frames.
59
61
  - A joined client re-requests it with `{ action: "presence", channel }`, answered to the SENDER only; a socket that never joined is REFUSED.
60
- - **Conversation frames — the transcript hydrates the client, so DO NOT build a hydration endpoint.**
62
+ - **Conversation frames** — the transcript hydrates the client (no hydration endpoint); editable or moderated content needs one of the two shapes below.
61
63
  - On a `conversation` channel the replay is PUSHED automatically at join, unasked: `conversation_start` (`payload.count`) → the last `limit` messages, each a normal `action: "message"` frame carrying its ORIGINAL `type` and `payload` plus `conversation: true` and the original `ts` → `conversation_end`.
62
- - Render `message` frames identically either way: no fetch or table read is needed to paint the initial view.
63
- - ⚠ `{ enabled: true }` alone is a no-op: `limit` defaults to 0 and 0 means RETAIN NONE (see `conversation` above) — always pass `limit`.
64
64
  - The POST-HANDLER broadcast payload IS the stored transcript row — a handler must broadcast everything the UI needs to render a past message (author name, id, `created_at`). Nothing else is replayed.
65
65
  - The transcript is a capped ring (`limit`, `ttl`), not storage: persist to a table only for durability, search, or reads beyond it.
66
+ - ⚠ APPEND-ONLY: the transcript records EVERY fanned-out frame — `s.realtime.publish` frames included, not only `"channel"`/`"others"` handler returns — and no entry can be edited or removed. A message deleted or EDITED in the DB is still replayed to every later joiner: both its original and any edited broadcast stay in the ring until `limit`/`ttl` evicts them, including across a `--keep-data` redeploy — so for editable/moderated content the transcript LEAKS retracted bodies. An ephemeral `deliverTo: "others"` frame (a typing indicator) also takes a ring slot, so a busy signal evicts real messages.
67
+ - Two safe shapes for editable/moderated chat: (a) turn `conversation` OFF, hydrate the initial view from a table endpoint, and keep the socket for live frames only; or (b) keep bodies OUT of the frames — publish ids only and read current bodies from a table — and put ephemeral signals (typing) on a SEPARATE channel with no `conversation`.
66
68
  - **`delivery.guarantee: "at_least_once"` is a CLIENT CONTRACT, not just a channel setting.**
67
69
  - The client must ACK what it receives — `{ action: "ack", channel, id }`, confirmed by `{ action: "ack", channel, payload: { cursor } }`.
68
70
  - ⚠ An ANONYMOUS client must ALSO send a durable `options.client_id` in its JOIN frame (once; later acks need not repeat it). WITHOUT one it has no cursor, its acks are SILENTLY IGNORED, and it degrades to at_most_once. An AUTHENTICATED client is keyed by identity and needs no `client_id`.
69
- - The missed gap arrives after join as `replay` frames, oldest-first, each with an `id` to ack. ⚠ A first join gets `cursor: "0"`: the WHOLE retained stream replays, repeating a `conversation` transcript.
71
+ - The missed gap arrives after join as `replay` frames, oldest-first, each with an `id` to ack. A first join gets `cursor: "0"`: the WHOLE retained stream replays, repeating a `conversation` transcript.
70
72
  - DISTINCT from the conversation transcript: `conversation_*` is the SHARED "what was said before I arrived", `replay` is the PER-CLIENT "what I missed while disconnected". Both may be on.
71
73
  - How far back `replay` reaches is sized by `conversation.ttl` (here a REAL per-message age cut, and it BEATS `limit`), else `conversation.limit`, else 1000 — even on a channel with no transcript enabled.
72
- - **What a message handler RETURNS decides delivery, and the failure directions are NOT symmetric.**
74
+ - **What a message handler RETURNS decides delivery:**
73
75
  - A returned value fans out per `deliverTo` and becomes the transcript row.
74
76
  - Returning NULL delivers NOTHING — the supported way to veto a message (the sender is told `dropped: true`).
75
77
  - A payload REJECTED by the declared `input` also delivers nothing; the detail goes ONLY to the sender.
76
- - ⚠ But a handler that CRASHES FAILS OPEN: the sender's ORIGINAL, UNVALIDATED payload is broadcast to the channel unchanged. A handler doing redaction or authorization must NOT be the only thing between client input and subscribers.
78
+ - ⚠ A handler that CRASHES FAILS OPEN — a failed `s.precondition`/`guard.*` (even in an `s.function.run` target), a throwing middleware, a runtime error: the sender's ORIGINAL, UNVALIDATED payload is broadcast unchanged (`s.throw` DROPS it). To veto, set the response var to `c.null()`.
package/llms/lambda.md CHANGED
@@ -2,19 +2,15 @@
2
2
 
3
3
  > Read when writing a JavaScript body, or weighing whether to reach for one at all — `lam.fn`, `fl.lambda`, `fl.reduce`, `s.lambda`; each surface binds a different set of identifiers.
4
4
 
5
- **A lambda is an escape hatch, not a default.** The body runs outside the request's own
6
- runtime, and a workspace has a BOUNDED pool of lambda workers every lambda in it shares
7
- — so a call both crosses a process boundary and draws on a workspace-wide resource.
8
- Reach for one only when the typed surface cannot express the work: if a native filter,
9
- an `expr(...)`/`obj(...)` expression, or a plain statement can, use that. The crossing
10
- is per CALL, not per element — an iterating filter sends the body ONCE and loops on the
11
- other side, so one body over a whole list beats one called from inside a stack loop.
5
+ **A lambda is an escape hatch, not a default.** Use one only when a native filter,
6
+ an `expr(...)`/`obj(...)` expression, or a statement can't do the work: each call crosses a
7
+ process boundary into a BOUNDED pool of lambda workers every lambda in the workspace shares.
8
+ The crossing is per CALL, not per element — an iterating filter sends the body ONCE and loops on the
9
+ other side, so one iterating filter over a list beats a lambda inside a stack loop.
12
10
 
13
11
  The lambda statement (`s.lambda({ as, code, timeout? })`) and eight filters run a
14
- JavaScript body. **Write the body as a FUNCTION, not a `c.text` string** — the
15
- bindings are its parameters, so the editor supplies them and a wrong name is a
16
- compile error instead of a wrong value at runtime. Write it inline and the surface
17
- is implied by where it sits; nothing names one:
12
+ JavaScript body. **Write the body as a FUNCTION, not a `c.text` string** (bindings are
13
+ typed parameters; a wrong name is a compile error). Inline, the surface is implied by where it sits:
18
14
 
19
15
  ```ts
20
16
  fl.map(({ $this }) => $this * 2) // map's bindings, typed from the position
@@ -22,19 +18,18 @@ fl.reduce({ initial_value: 0, code: ({ $result, $this }) => $result + $this })
22
18
  s.lambda({ as: "total", code: ({ $var }) => $var.subtotal * 1.2 }) // ambient only — $this is a compile error
23
19
  ```
24
20
 
25
- The parameters are a fiction — only the BODY is sent, and the engine injects the
26
- bindings as free identifiers — so DESTRUCTURE them as named: `(b) => b.$this`,
27
- `{ $this: x }`, nesting, a default or rest are undefined there (refused).
21
+ Destructure bindings by their exact names (`({ $this })`). Refused: `(b) => b.$this`,
22
+ renaming (`{ $this: x }`), nesting, defaults, rest.
28
23
 
29
24
  ⚠ An inline `code:` arrow receives BINDINGS ONLY. `capture` is an option of
30
25
  `lam.fn`, not a field of `s.lambda` or a filter, so `capture:` beside `code:` is a type
31
- error — the fix is to relocate the body, not to drop the field: `lam.fn(fn, { capture })` (below).
26
+ error — move the body into `lam.fn(fn, { capture })` (below).
32
27
 
33
28
  For a body built away from its call site:
34
29
 
35
30
  - `lam.fn(({ $result, $this }) => $result + $this, { surface?, capture? })` — name a `surface` to check it here, or omit it and the call site checks it.
36
31
  - `lam.raw("return 1", { surface })` — text, same validation.
37
- - `lam.raw(code, { surface, unchecked: true })` — sends a body that does not parse or declares a top-level `import`/`export` (a fixture pinning the engine's syntax-error answer, or a pulled body); skips those syntax checks only, here and at the `s.lambda` / `fl.*` site.
32
+ - `lam.raw(code, { surface, unchecked: true })` — sends a body that does not parse or declares a top-level `import`/`export`; skips those syntax checks only, here and at the `s.lambda` / `fl.*` site.
38
33
  - `lam.file("./lambdas/total.ts")` — a default-exported function in its own module (path relative to the caller), read as text at build time. NODE ONLY: `import { lam } from "@xano/sdk/node"` (isomorphic `lam` has no `file`). Only the default export's BODY is sent, so a value import, a second export or a top-level helper is refused — move helpers inside; `import type` / `import { type X }` are free. `@xano/sdk/lambda-globals` types the globals below program-wide: keep modules in `xano/lambdas/` (its scaffold tsconfig loads it) or `import type {} from` it under their own tsconfig.
39
34
 
40
35
  Nothing from the enclosing scope crosses: the body is sent as TEXT, so a closed-over
@@ -45,13 +40,12 @@ body needs in `capture`; it arrives as the SECOND parameter, emitted as a `const
45
40
  lam.fn(({ $this }, { capturedRate }) => $this * capturedRate, { surface: "map", capture: { capturedRate: rate } })
46
41
  ```
47
42
 
48
- ⚠ A capture key must NOT share its name with a module-scope binding: a `.ts` loader
49
- renames one of two same-named bindings, so the body reads `rate2` while the prelude
50
- declares `rate` (refused at build time). `capture: { capturedRate: rate }` is the safe form.
43
+ ⚠ A capture key must NOT share a module-scope binding's name (a `.ts` loader renames one;
44
+ refused at build time) — `capture: { capturedRate: rate }`, not `{ rate }`.
51
45
 
52
46
  Capture JSON data only: a function, `NaN`, a sparse/typed array or class instance (`Date`, `Map`…)
53
47
  is refused at build time, at any depth. Capture the plain form and rebuild in
54
- the body (`d.getTime()` → `new Date(d)`). The captured type flows into the second parameter.
48
+ the body (`d.getTime()` → `new Date(d)`).
55
49
 
56
50
  A body is a FUNCTION BODY: it must `return` its value. Bindings by surface — an
57
51
  identifier outside its surface's set is undefined at runtime, and the SDK refuses
@@ -68,12 +62,21 @@ an iterating filter and the piped value in `fl.lambda`; `$parent` is the whole a
68
62
  and exists only on the iterating filters. A stack variable is reached as
69
63
  `$var.name` — it is NOT also injected as a bare `$name`.
70
64
 
71
- Four hazards and the dependency route, all live-verified:
72
-
73
- - ⚠ A body that THROWS does not fail the request: the engine returns its diagnostic
74
- TEXT as the value with HTTP 200, so the failure reads as bad data. Validate before
75
- consuming a lambda result numerically, and prefer a `lam.*` body, which cannot fail
76
- this way for a binding reason.
65
+ `$auth` with no authenticated caller (a public surface, or an authed one reached without a
66
+ token) is `{ id: 0, dbo: "" }`, not null. Test `$auth.id > 0`, not truthiness.
67
+
68
+ Hazards:
69
+
70
+ - ⚠ A body that THROWS or times out does not fail the request (nor reach `s.try_catch`): the
71
+ engine returns its diagnostic TEXT as the value with HTTP 200 (`"[Line 1:Char 7] boom"`,
72
+ `"Lambda timed out after 1 seconds"`; a thrown non-Error is `" Unknown error"` on the cloud).
73
+ Validate before consuming it. To FAIL the request: wrap the body in `try { return { ok: true,
74
+ v } } catch { return { ok: false } }`, then `s.precondition` `ref("r.ok", { safe: true })` = `true`.
75
+ - ⚠ An `s.lambda` whose body returns a STRING that parses as a JSON object or array binds
76
+ the DECODED value, not the string (the statement's output is cast as `json`);
77
+ scalar-looking strings (`"123"`, `"true"`) stay text, and `fl.map`/`fl.lambda` keep
78
+ the string. A body that `JSON.stringify`s a payload to sign/hash/store gets an object
79
+ back. To keep text, return it WRAPPED (`{ text }`) and read `.text`.
77
80
  - ⚠ `timeout` is COOPERATIVE — observed only at an `await` — so it bounds WAITING (a slow
78
81
  `fetch`), not compute: a 1s `timeout` over a 3s busy-loop runs all 3s and returns
79
82
  normally. Bound a loop that could run away inside the body.
@@ -81,15 +84,24 @@ Four hazards and the dependency route, all live-verified:
81
84
  a dependency through the PRELOADED globals below. A dynamic `import("…")`/`require("…")`
82
85
  with a LITERAL specifier is not portable: an instance that bundles the body first
83
86
  returns the TEXT `Could not resolve "node:crypto"` with HTTP 200.
84
- - Preloaded globals, live-probed — no specifier, so these work everywhere:
87
+ - Preloaded globals — no specifier, so these work everywhere:
85
88
  `_` · `aws4` · `axios` · `cryptojs` · `DateTime` · `ethers` · `fastXmlParser` ·
86
89
  `jose` · `luxon` · `mailparser` · `math` · `moment` · `nodemailer` · `socks` ·
87
90
  `uuid` · `utils`
88
91
  …plus `fetch`, `Buffer`, `TextEncoder`/`TextDecoder`, and the `crypto` above
89
92
  (`randomUUID`, `createHmac`, `createHash`, `subtle`). `Object.keys(globalThis)`
90
93
  inside a body lists whatever else a given instance carries.
91
- - ⚠ `console` output goes to the request LOG, not stdout. `log` · `error` · `warn` ·
92
- `info` · `debug` · `trace` all route there; any other `console` method is undefined,
93
- and CALLING it throws (error text as the value, HTTP 200).
94
+ - An INLINE body in `xano/` that uses one of these globals does not type-check until that
95
+ file has `import type {} from "@xano/sdk/lambda-globals"` at the top (safe in the defs
96
+ program — it is not the frontend); or move the body to a `lam.file` module under
97
+ `xano/lambdas/`, whose scaffold tsconfig loads the types already.
98
+ - ⚠ `console` output goes to the request LOG, not stdout. The logging methods (`log` ·
99
+ `error` · `warn` · `info` · `debug` · `trace`), plus `table` and `dir`, all route there;
100
+ `group`/`count`/`time`/`assert` are undefined, and CALLING one throws (error text as the
101
+ value, HTTP 200).
94
102
 
95
103
  TypeScript annotations survive in the body, and top-level `await` works.
104
+
105
+ Inline and `lam.fn` bodies are stored WHITESPACE-MINIFIED on one line, so an error position
106
+ (`[Line 1:Char 59]`) always says Line 1. Use `lam.file` when you want the body readable or
107
+ line-accurate errors; its module text is stored as written.
package/llms/legacy.md CHANGED
@@ -2,16 +2,15 @@
2
2
 
3
3
  > Read when the code was PULLED from an existing Xano instance — how a codegen'd tree reads, the shapes in it that must not be "fixed", and any `raw({ name: "mvp:…" })`, `realtimeTrigger()`, or name the catalogs do not list.
4
4
 
5
- Older paradigms this SDK still supports and still emits when it decodes an existing
6
- workspace. **Do not author these.** They are listed by name only so you recognize them
5
+ Shapes codegen emits when it decodes an existing workspace, all supported.
6
+ **Do not author these.** They are listed by name only so you recognize them
7
7
  in pulled code rather than "fixing" them; each line names what to use instead.
8
8
 
9
- Names overlap across the split deliberately — the engine reused words like
10
- "realtime" and "channel" for both generations. A name matching is NOT evidence that
11
- two things are the same object; check which list it came from.
9
+ "realtime" and "channel" name objects in both lists: a matching name does NOT mean
10
+ the same object; check which list it came from.
12
11
 
13
12
  - `c.expressionLegacy` — the older `const:expr` expression form, emitted by codegen for workspaces that still hold one — author `c.expression` instead.
14
- - `realtimeTrigger()` — the SUPERSEDED realtime trigger, against the workspace-global realtime layer — a different object from the current `channel`, despite the similar name. For a join hook use `realtimeChannelTrigger({ actions: { join: true } })`; for message handling use a `realtimeMessage()` handler, which is the current equivalent of its `message` action (a message is an authored unit now, not a trigger action).
13
+ - `realtimeTrigger()` — the SUPERSEDED realtime trigger, against the workspace-global realtime layer — a different object from the current `channel`, despite the similar name. For a join hook use `realtimeChannelTrigger({ actions: { join: true } })`; for message handling use a `realtimeMessage()` handler, which is the equivalent of its `message` action (a message is its own object, not a trigger action).
15
14
  - `s.api.realtime_event` — publishes to the SUPERSEDED workspace-global realtime layer, NOT to a `realtimeChannel()` — its `channel` is a string against that layer, so pointing it at a current-layer channel path publishes into the void. Use `s.realtime.publish` instead: it names the owning `realtimeServer()`, so it addresses a real `realtimeChannel()`.
16
15
 
17
16
  Retired statements and statement VERSIONS — no `s.` surface exists. Pulled code shows
@@ -31,7 +30,7 @@ Statements the engine writes but will NOT import back — no `s.` surface exists
31
30
  unlike the retired versions above these must be FIXED, not left alone. Pulled code shows
32
31
  them as `raw({ name: "…" })`; `export()` refuses any bundle that still contains one.
33
32
 
34
- - `mvp:placeholder` — an unconfigured statement slot the engine writes in place of a statement it could not resolve, so an export stays well-formed. There is no statement class behind it: importing a workspace that contains one fails outright with "Missing statement: mvp:placeholder". Replace it with the statement it stands in for before deploying — there is no destination where it runs.
33
+ - `mvp:placeholder` — an unconfigured statement slot the engine writes for a statement it could not resolve. Importing a workspace that contains one fails with "Missing statement: mvp:placeholder" on every destination; replace it with the statement it stands in for before deploying.
35
34
 
36
35
  ## Reading a pulled tree
37
36
 
package/llms/lock.md CHANGED
@@ -6,7 +6,7 @@
6
6
  stay renames (guids otherwise derive from `(type, name)`; a query's from `(api group,
7
7
  verb, name)`). Committed. A composed entry is keyed by that identity —
8
8
  `query:<group>|<verb>|<name>`, `channel:<server>|<path>`, `message:<server>|<path>|<name>`
9
- — its guid's seed; a legacy `query:<name>` is migrated by the next locked export.
9
+ — its guid's seed; a bare `query:<name>` key is rewritten to the composed form by the next locked export.
10
10
 
11
11
  - `npx @xano/sdk lock rename <kind> <old> <new>` — `kind` is the SDK kind (`table`, `apiGroup`) or stored key (`dbo`).
12
12
  Run it when `export` names it after a rename in code (it prints the command); the next export emits the original guid under the new name.
@@ -22,19 +22,23 @@ verb, name)`). Committed. A composed entry is keyed by that identity —
22
22
  - Programmatic use: call `seedLockOverrides(readLockFile(path))` BEFORE importing any def
23
23
  module — references bake guids at import time; `writeBundle` refuses an unseeded lock.
24
24
 
25
- What writes the lock: `export`/`deploy`/`release`/`preflight` of an ENTRY FILE update it;
26
- `compile`/`paths` only READ. `--no-lock` builds
27
- without one (names derive guids, the instance invents public URLs, no `--prune`);
28
- REFUSED over a parseable lock. A DEPLOY or a RELEASE writes back only `landed`: what
29
- this project LANDED on each destination (ephemerals: `.xano/ephemeral.json`). `--prune` deletes only that — never a merely
30
- exported name; no record there, no prune until one landing (commit it). A `deploy` (`--replace`
31
- too) PRESERVES the archive's guids, so the lock still describes the rebuilt
32
- workspace. CI: `--frozen-lock` fails (`SDK_DRIFT`) instead of changing the lock, and fails while the lock
33
- carries an entry no exported object matches — a plain `export` only warns and writes that
34
- entry down, after which nothing tells a rename from a deletion: resolve it with
35
- `lock rename` or `lock prune`, or accept them with `--allow-lock-orphans` when they are the
36
- not-yet-ported half of an adopted workspace.
37
- `export --check` implies `--frozen-lock` and writes nothing — no bundle, no lock — so it
38
- reads no `xano/.env` or `.secrets.json` and refuses the flags that supply them; this is
39
- what `npm run xano:check` runs, so CI needs no secrets. With no lock at all, either flag
40
- fails only when the source has identities to record (an empty workspace passes).
25
+ ### Writers and readers
26
+
27
+ - `export`/`deploy`/`release`/`preflight` of an ENTRY FILE update the lock; `compile`/`routes` only READ.
28
+ - `--no-lock` builds without one (names derive guids, the instance invents public URLs, no `--prune`);
29
+ REFUSED over a parseable lock.
30
+ - A DEPLOY or a RELEASE writes back only `landed`: what this project LANDED on each destination
31
+ (ephemerals: `.xano/ephemeral.json`). `--prune` deletes only that, never a merely exported name;
32
+ no record there, no prune until one landing. Commit the lock.
33
+ - A `deploy` (`--replace` too) PRESERVES the archive's guids, so the lock still describes the rebuilt workspace.
34
+
35
+ ### CI
36
+
37
+ - `--frozen-lock` fails (`SDK_DRIFT`) instead of changing the lock, and fails while the lock carries
38
+ an entry no exported object matches. A plain `export` only warns and writes that entry down, after
39
+ which a rename and a deletion look the same. Resolve it with `lock rename` or `lock prune`, or
40
+ accept them with `--allow-lock-orphans` when they are the not-yet-ported half of an adopted workspace.
41
+ - `export --check` implies `--frozen-lock` and writes nothing — no bundle, no lock — so it
42
+ reads no `xano/.env` or `.secrets.json` and refuses the flags that supply them. `npm run xano:check` runs it,
43
+ so CI needs no secrets.
44
+ - With no lock at all, either flag fails only when the source has identities to record (an empty workspace passes).
@@ -2,23 +2,21 @@
2
2
 
3
3
  > Read when deciding WHAT to build — every authorable primitive, what each is, and which factory + register method builds it. Also when `register*` will not typecheck an array built by `.flatMap()`/`.concat()`.
4
4
 
5
- Author with the factory, register on the Xano instance, lands under the payload key. Each line ends with a one-liner on what the primitive is.
6
-
7
5
  ### Choosing a kind
8
6
 
9
- Choose by who or what starts the work. Each rule names the kind that fits and the one it gets mistaken for.
7
+ Choose by who or what starts the work.
10
8
 
11
9
  - **Logic other code calls** → `defineFunction`, run with `s.function.run`. A `query` is the only kind an HTTP client reaches by verb + path; a `tool` is what an `agent()` or an MCP client calls. Logic serving two callers (an endpoint AND a tool) lives in one function both call.
12
- - **Work on a timer** → `task` (cron or interval). **Work a request starts but does not wait for** → `s.function.run({ fn, runtime: { mode: "async-shared" } })`, which binds a job id, not the result (collect with `s.await`). **Work that follows a row change** → `tableTrigger`: it fires on every insert/update/delete of the table, whichever stack writes it, so the same side effect placed in one endpoint's stack misses every other write path.
13
- - **The same steps before or after many objects** (an auth check, a rate limit, logging) → `middleware`, attached per host (`middleware: { pre, post }` on a query, function, task, tool or API group) or to every host of a kind with `workspaceConfig({ middleware: { query, function, task, tool } })` — not a function call repeated at the top of each stack.
10
+ - **Work on a timer** → `task` (fixed interval, no cron). **Work a request starts but does not wait for** → `s.function.run({ fn, runtime: { mode: "async-shared" } })`, which binds a job id, not the result (collect with `s.await`). **Work that follows a row change** → `tableTrigger`: it fires on every write to the table, whichever stack writes it (except a trigger's own), so the same side effect in one endpoint's stack misses every other write path. It runs after commit, async — validation belongs in the writing stack (`llms/triggers.md`).
11
+ - **The same steps before or after many objects** (an auth check, a rate limit, logging) → `middleware`, attached per host (`middleware: { pre, post }` on a query, function, task, tool, API group, prompt, resource, or realtime server/channel/message) or to every host of a kind with `workspaceConfig({ middleware: { query, function, task, tool } })` — not a function call repeated at the top of each stack.
14
12
  - **Related rows on returned rows** → an `addon` attached to the read through its `addon: [{ addon, as, input }]` option (`db.query`/`get`/`add`/`edit`/`patch`), merged onto each row under `as` and typed in `InferResponse` — not a second read plus a loop that stitches rows together.
15
- - **AI.** An LLM running inside the backend → `agent()`, started from a stack with `s.ai.agent.run`; it has no public endpoint. An external AI client (Claude, Cursor, any MCP client) calling the backend → `mcpServer()`. Standing instructions for Xano's own builder AI → `knowledge()` (a local coding agent reads the same files in the repo); an `agent()` run never reads it. The actions either one calls → `tool()`. What an MCP server serves besides tools (`prompt()`, `resource()`) and when each fits: `llms/kinds-agent-mcp.md`.
13
+ - **AI.** An LLM running inside the backend → `agent()`, started from a stack with `s.ai.agent.run`; it has no public endpoint. An external AI client (Claude, Cursor, any MCP client) calling the backend → `mcpServer()`. Standing instructions for Xano's own builder AI → `knowledge()` (who reads it: `llms/kinds-knowledge.md`). The actions either one calls → `tool()`. What an MCP server serves besides tools (`prompt()`, `resource()`) and when each fits: `llms/kinds-agent-mcp.md`.
16
14
  - **Pushing to connected clients** → `realtimeServer` → `realtimeChannel` → `realtimeMessage` (the handler for a frame a client sends — the realtime analogue of a query). A server-side push from any stack is `s.realtime.publish`; a client polling a `query` is the substitute this replaces.
17
15
  - **Code the typed surface cannot express** → a lambda (`s.lambda`, `fl.lambda`) for a short JavaScript body, LAST, after native filters and expressions (`llms/lambda.md`); a `microservice` for a long-running container or another language; `s.api.request` for a service that already has an HTTP API.
18
16
  - **Tests** → `tests` on a `query`/`defineFunction`/`middleware` for that one object's input → output; a `workflowTest` for a flow across objects (`s.function.call`, `s.api.call`, `s.task.call`) asserted with `s.expect.*`.
19
17
  - **Reacting to the platform** → `errorTrigger` (an error signature first seen, regressing, or marked fixed) and `workspaceTrigger` (branch new/merge/live). What one connection to an MCP server, agent, realtime server or channel may see or do → that object's connection trigger.
20
18
 
21
- ⚠ Composing a workspace from independently-authored modules: `register*` takes its defs however they arrive, but `modules.flatMap((m) => m.tables)` does NOT typecheck. `Array.prototype.flatMap` binds its element type to the FIRST element, so every later module's tables are checked against that one table's schema — the error compares two unrelated column names and mentions neither `flatMap` nor the cause. `.concat()` collapses the same way. Two spellings work: pass an array LITERAL (`registerTables([...a.tables, ...b.tables])` — spreads are fine, TypeScript infers the union across every element at once), or annotate the module array with the wide aliases `AnyTableDef` / `AnyQueryDef` / `AnyFunctionDef` / `AnyAddonDef`, exported for exactly the four def types whose generics can collapse this way. Widening the array costs nothing: the typing you need lives on the `table()`/`query()` handle you hold and pass to `s.db.*`, and is never read back off the registered array.
19
+ Composing a workspace from modules: `registerTables(modules.flatMap((m) => m.tables))` does NOT typecheck — `flatMap` (and `.concat()`) binds its element type to the FIRST element, so later tables are checked against that one table's schema; the error names two unrelated columns, not the cause. Pass an array LITERAL (`registerTables([...a.tables, ...b.tables])`), or annotate the module array with the wide aliases `AnyTableDef` / `AnyQueryDef` / `AnyFunctionDef` / `AnyAddonDef`. Widening loses nothing: typing lives on the `table()`/`query()` handle passed to `s.db.*`.
22
20
 
23
21
  - function: `defineFunction` → `Xano.registerFunctions` → payload `function` — Reusable server-side logic (a custom function) callable from any stack via `s.function.run`.
24
22
  - table: `table` → `Xano.registerTables` → payload `dbo` — A database table: typed columns (`f.*`), indexes, and views; the schema other kinds read and write.
@@ -36,13 +34,13 @@ Choose by who or what starts the work. Each rule names the kind that fits and th
36
34
  - resource: `resource` → `Xano.registerResources` → payload `resource` — An MCP resource: contents an MCP client reads by URI (a literal or a `{variable}` template), produced by a stack. Exposed by an `mcpServer`.
37
35
  - mcp_server: `mcpServer` → `Xano.registerMcpServers` → payload `toolset` — An MCP server exposing tools, prompts and resources to external MCP clients.
38
36
  - agent: `agent` → `Xano.registerAgents` → payload `toolset` — An AI agent: an LLM configuration plus the tools it can call. Invoke it from any stack (query/function/task/tool/trigger) with `s.ai.agent.run` — no public endpoint; the result is a rich envelope whose completion text is at `.result`.
39
- - task: `task` → `Xano.registerTasks` → payload `task` — A scheduled background job (cron/interval) that runs a stack on a timer.
40
- - workflow_test: `workflowTest` → `Xano.registerWorkflowTests` → payload `workflow_test` — An end-to-end test: a named stack with NO input and NO response that invokes other objects (`s.function.call`, `s.task.call`, `s.api.call`) and asserts on what they bind with `s.expect.*`. `datasource` defaults to `""` (an EMPTY datasource, recommended); naming one CLONES it before every run — see `llms/kinds-core.md`.
41
- - middleware: `middleware` → `Xano.registerMiddleware` → payload `middleware` — A reusable pre/post stack attached to a query/function/task/tool/API group to run before or after its own logic.
37
+ - task: `task` → `Xano.registerTasks` → payload `task` — A scheduled background job that runs a stack on a fixed interval (no cron).
38
+ - workflow_test: `workflowTest` → `Xano.registerWorkflowTests` → payload `workflow_test` — An end-to-end test: a named stack with NO input and NO response that invokes other objects (`s.function.call`, `s.task.call`, `s.api.call`) and asserts on what they bind with `s.expect.*`. `datasource`: `llms/kinds-core.md`.
39
+ - middleware: `middleware` → `Xano.registerMiddleware` → payload `middleware` — A reusable pre/post stack attached to a host (query, function, task, tool, API group, prompt, resource, realtime server/channel/message) to run before or after its own logic.
42
40
  - addon: `addon` → `Xano.registerAddons` → payload `addon` — A reusable read fragment that enriches a query result by joining related table data.
43
41
  - realtime_server: `realtimeServer` → `Xano.registerRealtimeServers` → payload `realtime_server` — A realtime (websocket) server: the canonical-addressed container that owns realtime channels. Off until `enabled: true`. Returns a handle with `getUrl(baseUrl)`/`getPath()` for the client's socket URL (`wss://<host>/ws/<canonical>`).
44
42
  - channel: `realtimeChannel` → `Xano.registerRealtimeChannels` → payload `channel` — A realtime channel: a joinable path on a realtime server (`rooms/{room_id}`) with typed path params, join/publish policy, a client-visible conversation transcript, and delivery semantics. Owns message handlers. Returns a handle with `getChannel(params)` for the path a client joins.
45
43
  - message: `realtimeMessage` → `Xano.registerRealtimeMessages` → payload `message` — A realtime message handler: a named message type on a channel with its own typed payload and stack — the realtime analogue of a query. Pass the `realtimeChannel()` handle as `channel` and the owning server comes with it.
46
44
  - microservice: `microservice` → `Xano.registerMicroservices` → payload `microservice` — A container workload deployed alongside the workspace, called from a stack with `s.microservice.request`. Def shapes (`builtin` containers vs a `helm` chart) and the SECRET-handling rules its config carries: `llms/statements-calls.md`.
47
- - knowledge: `knowledge` → `Xano.registerKnowledge` → payload `knowledge` — Markdown shared by every AI that builds the backend — Xano's own AI (the builder agent, Meta API / MCP readers) and a local coding agent reading the same files — never an `agent()` run: an `agents.md` of standing instructions, a `skill`, or a `doc`. The body is a real markdown FILE via `knowledgeFile("./x.md", import.meta.url)`, and `mode` decides how much of it reaches the agent.
45
+ - knowledge: `knowledge` → `Xano.registerKnowledge` → payload `knowledge` — Markdown for the AIs that build the backend (never an `agent()` run): an `agents.md` of standing instructions, a `skill`, or a `doc`. The body is a markdown FILE via `knowledgeFile("./x.md", import.meta.url)`; readers and `mode`: `llms/kinds-knowledge.md`.
48
46
  - workspace: `workspaceConfig` → `Xano.registerWorkspace` → payload `workspace` — Workspace-level configuration such as default middleware chains and request-history defaults per host kind.