@hanger-source/agentic-olap 0.14.1 → 0.15.1

package/licenses/jvm/dependencies.json

@@ -365,81 +365,97 @@
         ]
     },
     {
-        "coordinate": "org.jetbrains.kotlin:kotlin-compiler-embeddable:2.2.21",
-        "jar": "kotlin-compiler-embeddable-2.2.21.jar",
-        "sha256": "9588fa696ac5507af764fd5660df6894185e12704ec1bc3f5cb772af4987f295",
+        "coordinate": "org.jetbrains.kotlin:kotlin-build-tools-api:2.4.21",
+        "jar": "kotlin-build-tools-api-2.4.21.jar",
+        "sha256": "c5cd6a49bd072b529ae10809111c16a7aa0f92147e95d288354017fd65799461",
         "embeddedNotices": [
             
         ]
     },
     {
-        "coordinate": "org.jetbrains.kotlin:kotlin-daemon-embeddable:2.2.21",
-        "jar": "kotlin-daemon-embeddable-2.2.21.jar",
-        "sha256": "91c0673c22e44b054ae0314d323860ebe1f3aff3f0ebc74fff82c4733dde09be",
+        "coordinate": "org.jetbrains.kotlin:kotlin-compiler-embeddable:2.4.21",
+        "jar": "kotlin-compiler-embeddable-2.4.21.jar",
+        "sha256": "ef19419c765e7ac8404465fa026ca8fc4dbb8a822de0fc79aa53c8dce29f1d02",
         "embeddedNotices": [
             
         ]
     },
     {
-        "coordinate": "org.jetbrains.kotlin:kotlin-reflect:2.2.21",
-        "jar": "kotlin-reflect-2.2.21.jar",
-        "sha256": "44380abf37d245ce5c0f294f43512d1c39a59642bfa463922c74e96877cf49f8",
+        "coordinate": "org.jetbrains.kotlin:kotlin-daemon-embeddable:2.4.21",
+        "jar": "kotlin-daemon-embeddable-2.4.21.jar",
+        "sha256": "7b3ef24674e5bcffcadfc4e43202ea314194939ecbcdd90a4770b2f1b04e0d07",
         "embeddedNotices": [
             
         ]
     },
     {
-        "coordinate": "org.jetbrains.kotlin:kotlin-script-runtime:2.2.21",
-        "jar": "kotlin-script-runtime-2.2.21.jar",
-        "sha256": "2b1519b427b514d1536c1b425674b03fe914af637924028e9959c6625442df51",
+        "coordinate": "org.jetbrains.kotlin:kotlin-reflect:1.6.10",
+        "jar": "kotlin-reflect-1.6.10.jar",
+        "sha256": "3277ac102ae17aad10a55abec75ff5696c8d109790396434b496e75087854203",
         "embeddedNotices": [
             
         ]
     },
     {
-        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-common:2.2.21",
-        "jar": "kotlin-scripting-common-2.2.21.jar",
-        "sha256": "414ed91c3f5e4492b23cb9537842b4651038e25dad84107939f434c2203f2a92",
+        "coordinate": "org.jetbrains.kotlin:kotlin-reflect:2.4.21",
+        "jar": "kotlin-reflect-2.4.21.jar",
+        "sha256": "7c9e8bda3cafa85b65692065acd22578b2843292b4e4baa8361bdc9175746e88",
         "embeddedNotices": [
             
         ]
     },
     {
-        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:2.2.21",
-        "jar": "kotlin-scripting-compiler-embeddable-2.2.21.jar",
-        "sha256": "d934b9d0c246bc09624b7068af58ad57cef11dbe2addbc7b19d250cce42de1c9",
+        "coordinate": "org.jetbrains.kotlin:kotlin-script-runtime:2.4.21",
+        "jar": "kotlin-script-runtime-2.4.21.jar",
+        "sha256": "a658cf5902a1525a06c264a5e42b437e97a6679ddeef8ca641246f270cf6a013",
         "embeddedNotices": [
             
         ]
     },
     {
-        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-compiler-impl-embeddable:2.2.21",
-        "jar": "kotlin-scripting-compiler-impl-embeddable-2.2.21.jar",
-        "sha256": "788a3060c8e7997f8ae16ba5c0280d05005af0a42029f18cb10c5625b979fac3",
+        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-common:2.4.21",
+        "jar": "kotlin-scripting-common-2.4.21.jar",
+        "sha256": "67817eeee13da1f827f7ab9b961e300c2a6c612c290dfebb12db2eafcf0813b3",
         "embeddedNotices": [
             
         ]
     },
     {
-        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-jvm-host:2.2.21",
-        "jar": "kotlin-scripting-jvm-host-2.2.21.jar",
-        "sha256": "ef72f73d752157c9a57e2a6e173a80be5304023b25caf86bd6b5b17cc5e37ada",
+        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:2.4.21",
+        "jar": "kotlin-scripting-compiler-embeddable-2.4.21.jar",
+        "sha256": "a9a2f4aab2d01ebec3a8ba91c4cc07a4589205867378e98854f2a3d0ecf0f31a",
         "embeddedNotices": [
             
         ]
     },
     {
-        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-jvm:2.2.21",
-        "jar": "kotlin-scripting-jvm-2.2.21.jar",
-        "sha256": "83820c5fcc5d28f045f914ecd5900bbbcf8115b0d7007334de069fe6c70669e6",
+        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-compiler-impl-embeddable:2.4.21",
+        "jar": "kotlin-scripting-compiler-impl-embeddable-2.4.21.jar",
+        "sha256": "5794e84bb83b855540c1105997a5963745d7c15d12654bb07304bb115564a7cb",
         "embeddedNotices": [
             
         ]
     },
     {
-        "coordinate": "org.jetbrains.kotlin:kotlin-stdlib:2.2.21",
-        "jar": "kotlin-stdlib-2.2.21.jar",
-        "sha256": "6558a3d233da56a20934b32159f9db5f86ed5816ef098f78a2c223dc6abb79dd",
+        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-jvm-host:2.4.21",
+        "jar": "kotlin-scripting-jvm-host-2.4.21.jar",
+        "sha256": "d5532c9aa1c54b982886c5424c6a7e5ce878ad886c2aaae14c167a5f876f67ec",
+        "embeddedNotices": [
+            
+        ]
+    },
+    {
+        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-jvm:2.4.21",
+        "jar": "kotlin-scripting-jvm-2.4.21.jar",
+        "sha256": "f00bc053865d7c2864e26087ce50b60ee8bdd30f9a252890d21a34e35d398f17",
+        "embeddedNotices": [
+            
+        ]
+    },
+    {
+        "coordinate": "org.jetbrains.kotlin:kotlin-stdlib:2.4.21",
+        "jar": "kotlin-stdlib-2.4.21.jar",
+        "sha256": "bd8250210584cb659847dce9cda660f8e9906e5def7fbebcea93dc6dcb6a88a3",
         "embeddedNotices": [
             
         ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanger-source/agentic-olap",
-  "version": "0.14.1",
+  "version": "0.15.1",
   "description": "Installable Agentic OLAP service and command-line client with bundled runtimes",
   "license": "Apache-2.0",
   "author": "hanger",

package/resources.json

@@ -6,16 +6,16 @@
   ],
   "sdk": "sdk",
   "sdkArtifacts": {
-    "connector-api": "com.github.hanger-source.agentic-olap:connector-api:v0.14.1",
-    "connector-loader": "com.github.hanger-source.agentic-olap:connector-loader:v0.14.1",
-    "engine-core": "com.github.hanger-source.agentic-olap:engine-core:v0.14.1",
-    "execution-calcite": "com.github.hanger-source.agentic-olap:execution-calcite:v0.14.1",
-    "execution-catalog": "com.github.hanger-source.agentic-olap:execution-catalog:v0.14.1",
-    "olap-contracts": "com.github.hanger-source.agentic-olap:olap-contracts:v0.14.1",
-    "semantic-calcite": "com.github.hanger-source.agentic-olap:semantic-calcite:v0.14.1",
-    "warehouse-contracts": "com.github.hanger-source.agentic-olap:warehouse-contracts:v0.14.1",
-    "warehouse-jdbc": "com.github.hanger-source.agentic-olap:warehouse-jdbc:v0.14.1"
+    "connector-api": "com.github.hanger-source.agentic-olap:connector-api:v0.15.1",
+    "connector-loader": "com.github.hanger-source.agentic-olap:connector-loader:v0.15.1",
+    "engine-core": "com.github.hanger-source.agentic-olap:engine-core:v0.15.1",
+    "execution-calcite": "com.github.hanger-source.agentic-olap:execution-calcite:v0.15.1",
+    "execution-catalog": "com.github.hanger-source.agentic-olap:execution-catalog:v0.15.1",
+    "olap-contracts": "com.github.hanger-source.agentic-olap:olap-contracts:v0.15.1",
+    "semantic-calcite": "com.github.hanger-source.agentic-olap:semantic-calcite:v0.15.1",
+    "warehouse-contracts": "com.github.hanger-source.agentic-olap:warehouse-contracts:v0.15.1",
+    "warehouse-jdbc": "com.github.hanger-source.agentic-olap:warehouse-jdbc:v0.15.1"
   },
   "sdkRepository": "https://jitpack.io",
-  "version": "0.14.1"
+  "version": "0.15.1"
 }

package/sdk/API.md

@@ -2,10 +2,12 @@
 
 `connector-api` 为独立后端实现提供共同合同和 Calcite 1.42.0 的公开类型。它不依赖治理、服务应用或内部编译实现。连接器实现已定义语义的原生映射与来源访问，业务指标、对象资格、数量、NULL 与查询组织仍由语义定义和共同内核拥有。
 
-SDK 按精确发行标签发布到 JitPack。`agentic-olap sdk` 返回本版 API、随包文档、Maven 仓库及 `artifacts` 中的完整坐标；`sdk --repository` 只输出仓库地址。构件使用 `com.github.hanger-source.agentic-olap` group，版本为 `v` 加产品版本，公开入口为 `connector-api`，可复用 JDBC 支持为 `warehouse-jdbc`，应用装载器为 `connector-loader`。使用命令返回的精确版本，不使用 SNAPSHOT。API 标识为 `agentic-olap-connector/v12-kotlin-native-collection-placement-calcite-1.42`。
+SDK 按精确发行标签发布到 JitPack。`agentic-olap sdk` 返回本版 API、随包文档、Maven 仓库及 `artifacts` 中的完整坐标；`sdk --repository` 只输出仓库地址。构件使用 `com.github.hanger-source.agentic-olap` group，版本为 `v` 加产品版本，公开入口为 `connector-api`，可复用 JDBC 支持为 `warehouse-jdbc`，应用装载器为 `connector-loader`。新建或确需重新构建的插件使用目标宿主命令返回的精确坐标，不使用 SNAPSHOT。API 标识为 `agentic-olap-connector/v12-kotlin-native-collection-placement-calcite-1.42`。
 
 SDK 的 JAR、POM 由插件工程的 Gradle 从 JitPack 匿名取得，第三方传递依赖从 Maven Central 取得。插件开发仍需 Kotlin/Gradle 工具链；运行产品无需这些构建工具。部署到其他服务前核对该服务的实际 API，不能把本地安装版本当作远程运行版本。
 
+产品版本或 SDK 坐标变化本身不要求重新构建插件。同一连接器 API 下，插件实际使用的公共 ABI 及 JVM、Kotlin、Calcite 要求仍满足时，可以沿用原完整插件组、manifest、`ConnectorRef` 和来源绑定。装载器核验精确字节与接口身份，不比较插件构建时的产品版本；API 字符串相同或装载成功，也不单独证明所有延迟执行分支可用。真正更换构件字节时，生成新的精确引用及来源绑定，通过现有显式治理修订、采用和发布处理变化，不能覆写旧字节或自动切换已有发布。
+
 `OlapConnector` 使用 Kotlin 接口，通过 JVM ServiceLoader 注册；只读属性 `id`、`version`、`apiVersion`、`compilation` 声明实现与编译能力，`access(verifiedIdentity)` 接收装载器核验后的精确身份并返回来源访问实现。发现和纯编译不读取源凭据、不打开业务连接。原生类型、参数、转换、数值失败与标量解码按实际输入类型实现，不支持的映射明确拒绝。
 
 完整服务的配置、精确绑定、显式结构登记、可选调查、结果交付与能力检查见[来源访问扩展](SOURCE-ACCESS.md)。SDK 和插件必须匹配服务实际 API。`JdbcAccess : SourceAccess` 是可选 JDBC 扩展，通过只读属性 `jdbc` 提供 `JdbcSupport`；`JdbcSourceAccess` 实现该合同。通用服务依赖 `SourceAccess`，HTTP 等插件无需实现 `JdbcAccess`。
@@ -81,7 +83,9 @@ AVG 的类型容量、算术正确性与舍入必须共同成立。`typeSystem.d
 
 `SourceAccess.execute` 拥有本次全部保证。访问层的 `CONSISTENT_READ` 要求检查与计算针对一致数据状态成立，可使用事务快照、原子 statement 或不可变数据版本，不把 `TRANSACTION_SNAPSHOT` 作为所有实现的前置。源端真实强制且覆盖既有数据的约束，也可在核验精确对象并保证执行期间 schema 稳定后兑现相应保证；仅目录 NULL 标记、约束名称、历史调查、DECLARED 或只检查后续写入的约束都不够。仅支持原生非空约束不代表能向优化器提供所有冻结键。内置 JDBC 继续使用数据非空见证，不因新增文档路径跳过扫描。
 
-同一原子 statement 的实现须保证必要检查不会因主结果为空、优化器裁剪、延迟求值或结果预算而跳过，并让违例传播为失败；一次 HTTP、SQL 批次或未被消费的 CTE 不是证明。插件保留核心主 SQL、检查 SQL 及各自参数的语义，不用 COUNT 前置、空人口跳过或运行后切换方式替代保证。发现真实 NULL 抛出 `SourceGuaranteeException("SOURCE_NOT_NULL_VIOLATION")`；能力不足使用 `SourceCapabilityException`，保留实际来源请求和阶段，不把无法核验写成数据已违例。单次执行保证可成立而 `readBasis` 仍为 Unknown；Unknown 不提供可重放版本坐标。完整机制条件与错误边界见[来源访问合同](SOURCE-ACCESS.md)。
+同一原子 statement 的实现须保证必要检查不会因主结果为空、优化器裁剪、延迟求值或结果预算而跳过，并让违例传播为失败；一次 HTTP、SQL 外壳、批次或未被消费的 CTE 不是证明。共同交付检查证据和主结果时，零行主结果也不能丢失必要证据。固定输入成功不替代真实物理来源路径；后端拒绝运输形态时保留原失败，不据常量结果声明能力已经兑现。插件保留核心主 SQL、检查 SQL 及各自参数的语义，不用 COUNT 前置、空人口跳过或运行后切换方式替代保证。发现真实 NULL 抛出 `SourceGuaranteeException("SOURCE_NOT_NULL_VIOLATION")`；能力不足使用 `SourceCapabilityException`，保留实际来源请求和阶段，不把无法核验写成数据已违例。单次执行保证可成立而 `readBasis` 仍为 Unknown；Unknown 不提供可重放版本坐标。完整机制条件与错误边界见[来源访问合同](SOURCE-ACCESS.md)。
+
+主 SQL 拥有最终结果的选行与行序语义，`SourceSqlRequest` 不另行提供排序键；`aliasMapping/outputTypes` 只是列合同。访问实现按来源返回顺序构造 `ResultFrame.rows`，运输、分页或预算处理不改变已有选行、重复度和排序。窗口排序、TopN 选行或集合内部排序不自动给出最终展示顺序；主 SQL 未给最终排序时不承诺稳定行序，并列键未区分的行也不额外确定顺序。不能仅凭有序子查询的样本认定外层 ARRAY／聚合会保序，也不能解析主 SQL 重建查询或在客户端重排来代替来源保证。
 
 集合结果、逐项展开、排序和文本显示分别声明 `COLLECTION_RESULTS/EXPANSION/SORT/TEXT` 能力。`sortCollection` 映射明确的方向及 NULL 顺序，`collectionText` 映射明确的分隔符与 NULL 替代；不能把数组提前解码成字符串代替这些运算。
 
@@ -94,7 +98,7 @@ AVG 的类型容量、算术正确性与舍入必须共同成立。`typeSystem.d
 
 内核拥有输入人口、输出投影和 INNER／OUTER：NULL 数组或空数组在 INNER 下无记录，在 OUTER 下补一个 NULL 元素及 NULL 序号；实际 NULL 元素有自己的非 NULL 序号，重复元素不丢弃。FROM 计划由核心 LEFT JOIN 并依据真实位置的非空性补整元素 NULL。输入投影计划的 OUTER 另需明确声明 `COLLECTION_PROJECTION_OUTER`：核心用标准 CARDINALITY 绑定存在标记，将 NULL／空数组替换为仅含一个 typed NULL 的同元素类型数组；生成后按存在标记将整个元素和序号置 NULL，原始输入列仍原样透传。该能力要求插件的原生类型与方言兑现 CARDINALITY、typed singleton ARRAY、CASE 和完整 ROW NULL 的组合；接受的类型超出保证时明确拒绝。缺少能力时在提交来源前返回 `NATIVE_COMPILATION_CAPABILITY_MISSING`、`capability=COLLECTION_PROJECTION_OUTER`、`operation=EXPAND_COLLECTION_OUTER`，不将 INNER 非空样本当作 OUTER 证明。
 
-序号从 1 开始，实际元素的 `ordinal` 必须非 NULL；不直接暴露原生数组下界，不凭元素或所有 ROW 字段为 NULL 推断缺行。映射不得自行过滤、去重、归约、复制输入或改变求值作用域；生成与取值针对同一条输入记录的同一绑定数组。运行验证须覆盖真实表行与聚合输入、空／NULL 数组、整体 NULL ROW、字段全 NULL 的非空 ROW、重复元素及位置规范化。其他后端上的通用 fixture 或常量数组成功不替代目标后端的正式 Query 验收。
+序号从 1 开始，实际元素的 `ordinal` 必须非 NULL；不直接暴露原生数组下界，不凭元素或所有 ROW 字段为 NULL 推断缺行。映射不得自行过滤、去重、归约、复制输入或改变求值作用域；生成与取值针对同一条输入记录的同一绑定数组，中间 ARRAY／ROW 保留类型与身份，不能压成展示字符串。运行验证须覆盖真实表行与聚合输入、空／NULL 数组、整体 NULL ROW、字段全 NULL 的非空 ROW、重复元素及位置规范化。其他后端上的通用 fixture 或常量数组成功不替代目标后端的正式 Query 验收；固定零行／一行外壳可能被折叠，不能证明物理扫描或原生引擎之间的集合类型传递已经成立。
 
 零条输入关系与一条输入记录上的 NULL／空数组是不同人口。带分组键的聚合在零条输入时不产生分组；集合聚合的 typed NULL 分支保留该聚合声明的空输入含义，不会创建分组。INNER 展开不制造输入记录，OUTER 只保留实际存在的输入记录。插件不能用预先 COUNT、跳过执行、额外分组、删除透传列或外围 SQL 改写来掩盖来源错误。
 
@@ -125,7 +129,7 @@ lowering 结果在本次计算内持有与精确引用对应的同一编译支
 独立 Kotlin 插件工程从 SDK 仓库声明宿主提供的公开构件，例如 Gradle Kotlin DSL：
 
 ```kotlin
-plugins { kotlin("jvm") version "2.2.21" }
+plugins { kotlin("jvm") version "2.4.21" }
 
 repositories {
     mavenCentral()

package/sdk/SOURCE-ACCESS.md

@@ -2,7 +2,7 @@
 
 完整 MCP 服务通过来源插件访问数据。使用方提供与其网络、鉴权和查询协议相符的插件，服务负责语义管理、发布、规划、SQL 生成、执行要求检查及结果合同校验。HTTP 查询服务是来源访问实现，不需要数据库端口、JDBC URL、数据库凭据或 catalog 权限。业务公式、资格规则和指标组合仍通过语义定义和 Query 表达。
 
-本文描述源码中的来源访问合同：连接器 API 为 `agentic-olap-connector/v12-kotlin-native-collection-placement-calcite-1.42`，元数据存储格式为 `16`。服务、SDK 与插件须来自同一发行或同轮源码构建，安装发行物时以该发行声明及实际服务合同为准。旧存储格式明确拒绝，服务不会自动改写已有持久根。
+本文描述源码中的来源访问合同：连接器 API 为 `agentic-olap-connector/v12-kotlin-native-collection-placement-calcite-1.42`，元数据存储格式为 `16`。产品运行构件按同一发行装配；独立插件核对目标宿主的连接器合同与实际运行要求，产品版或 SDK 坐标变化本身不要求重构原插件，具体采用规则见[安装与发布](installation-release.md)。旧存储格式明确拒绝，服务不会自动改写已有持久根。
 
 ## 配置来源
 
@@ -81,7 +81,7 @@ JDBC 实现的 `identityParameters` 为 `jdbcUrl`、可选 `username` 和 `drive
 
 源端原生强制约束可以免去同一非空条件的数据扫描，但插件必须核验约束确实作用于本次精确来源和列、覆盖已有数据与本次可读数据，而且在主查询期间不会因 DDL、表替换或连接切换失效。仅约束名称相同、目录返回 `nullable=false`、只约束后续写入、一次历史 catalog 观察或 `DECLARED` 结构都不足以证明这些条件。核验与使用之间的 schema 稳定性应由来源实际机制保证，例如同一受保护事务或 statement 的稳定 schema；不能靠先查目录再独立提交查询推断。源端只兑现非空约束时，也不能据此声明可以为优化器兑现所有冻结 PK／UK 等约束。
 
-插件选择同一原子 statement 进行数据见证或关系检查时，必须有目标来源的真实执行机制保证每项必要检查都会执行并将违例传播为失败，即使主结果为空、优化器裁剪了投影或分支、或者结果读取达到预算。把检查放进可能未被读取的 CTE、投影或交叉连接不构成这种保证；仅声明 statement snapshot 也不证明检查实际执行。没有通用 SQL 包装模板能替所有来源兑现这项责任。插件保持核心主 SQL 的人口、NULL、重复度和求值语义，不用前置 COUNT、跳过空人口或失败后换方案替代核验。
+插件选择同一原子 statement 进行数据见证或关系检查时，必须有目标来源的真实执行机制保证每项必要检查都会执行并将违例传播为失败，即使主结果为空、优化器裁剪了投影或分支、或者结果读取达到预算。把检查放进可能未被读取的 CTE、投影或交叉连接不构成这种保证；一次 HTTP、一个 SQL 外壳或 statement snapshot 声明也不证明检查实际执行。共同返回检查证据和主结果的运输实现，不能因主结果零行而丢失必要证据。没有通用 SQL 包装模板能替所有来源兑现这项责任；物理来源路径被后端拒绝时应保留真实失败，不能把常量输入的成功当作能力已兑现。插件保持核心主 SQL 的人口、NULL、重复度和求值语义，不用前置 COUNT、跳过空人口或失败后换方案替代核验。
 
 发现采用列存在 NULL 时返回 `SourceGuaranteeException("SOURCE_NOT_NULL_VIOLATION")`；精确来源、类型或约束已变化时返回对应 `SOURCE_BINDING_DRIFT`、`SOURCE_COLUMN_TYPE_DRIFT` 或 `SOURCE_CONSTRAINT_DRIFT`。无法核验或无法维持所需一致性时准确拒绝能力或报告保证核验失败，不能报成已发现数据违例。HTTP 插件可用 `SourceExecutionException` 保留实际阶段、请求接受与执行状态；仅能确认查询已提交时，不把状态填成 `NOT_SUBMITTED`。原生异常与完整诊断保留为私有 cause，不把 SQL 或来源原文放入公开消息。
 
@@ -128,6 +128,8 @@ olap.output(olap.sources.connectorCapabilities(
 
 `expandCollection(outputType,tableAlias)` 返回原生展开的放置计划：`CollectionExpansion.Relation` 提供 FROM 生成器，`InputProjection` 提供完整输入上的单个 SELECT-list SRF；取值回调只接收当前作用域的数组和生成值引用，返回完整元素与序号表达式。核心构造输入透传、逐行人口、INNER／OUTER 及输出投影，不向插件开放任意关系改写。FROM 计划用核心 LEFT JOIN 兑现 OUTER；输入投影的 OUTER 要求明确的 `COLLECTION_PROJECTION_OUTER`，由核心绑定存在标记、用 typed singleton NULL 数组保留空／NULL 输入，再补整个元素和序号 NULL。该原生类型与方言组合未兑现时，编译以 `NATIVE_COMPILATION_CAPABILITY_MISSING` 和 `EXPAND_COLLECTION_OUTER` 明确拒绝。实际 NULL 元素仍有从 1 开始的位置，重复度、完整 ROW 和求值作用域不变。完整接口与原生映射范式见[连接器 API](API.md)。常量数组或其他后端的成功不替代真实表行、聚合结果及目标后端正式 Query 的验收。
 
+零条输入关系、已存在记录上的 NULL／空数组、NULL 元素及字段全 NULL 的非空 ROW 分别保留自身含义。固定零行或一行的完整集合外壳可能被常量折叠，不能据此推定物理扫描、原生引擎之间的类型传递或记录描述符同样可用；不同 Unknown 读基础下的空人口失败与非空成功也不能定位唯一根因。插件依据实际原生类型和执行路径调查，不删除元素、序号或输入透传列，不将中间 ARRAY／ROW 压成展示字符串来绕过类型边界。
+
 `textIdentityEquals(builder,left,right)` 接收两个保留真实类型的操作数，为文本身份 EQ、NE、IN 提供完整的 BOOLEAN 比较表达式，遵循 SQL 三值逻辑，不能隐式忽略大小写、尾空格或做 Unicode 归一。原生文本等号是否等价取决于实际类型、编码与 collation；样本相等和估算成本下降都不足以证明普遍等价。插件直接映射完整比较，不必将文本冒充二进制，也不必在 SQL 字符串中寻找操作数。数据库、列或比较策略中影响该保证的条件属于身份与来源保证，不能放入运行参数。这个合同不重新定义所有 CHAR、GROUP BY 或 ORDER BY 行为。
 
 插件的原生 Rex 函数还须诚实声明 NULL 传播，供 Calcite 分析真实过滤条件。返回类型可空不等于严格 NULL 传播；仅当函数严格传播 NULL 且非 NULL 输入不产生 NULL 时，才可用正式 `SqlOperator.getStrongPolicyInference()` 声明 `Strong.Policy.ANY`。内置 DuckDB `ENCODE` 和 H2 `RAWTOHEX/STRINGTOUTF8` 使用这一声明，原生 SQL 与身份比较语义不变。无法证明时，核心仍保留运行关系检查，不据插件函数名或可空类型免除 NULL、人口、重复度与数量边界。
@@ -156,7 +158,9 @@ olap.output(olap.sources.connectorCapabilities(
 
 插件返回 `SourceExecutionResult(frame,readBasis,request)`，其中 `frame` 是 `ResultFrame`。列必须与核心给定别名、顺序和类型一致；技术类型可以来自来源响应，也可以来自使用方明确的类型合同。`JdbcColumnType` 在这里是 SQL 标准类型码、原生类型名、精度、标度和可空性的值对象，不要求 `ResultSetMetaData`、`Connection` 或任何 JDBC 驱动。
 
-请求中的 `ResultValueType.Scalar` 用可空的 `Integer precision/scale` 表达 SQL 类型容量；未指定时为 `null`，不使用负数哨兵，也不能擅自补成零。DECIMAL 必须给出正精度及 `0..precision` 内的小数位。插件按同轮 SDK 编译并明确处理这些可空字段，装载器按精确连接器 API 标识检查接口。
+结果行序由完整主 SQL 的最终排序语义决定，访问实现按来源返回顺序物化，核心继续保留该行列表。窗口内的排序、TopN 的选行顺序和集合内部排序不自动构成最终结果的展示排序；没有最终 `ORDER BY` 时不承诺稳定行序，排序键未区分的并列行不额外确定顺序。`SourceSqlRequest` 不另给独立排序键，列别名映射与输出类型不能当作排序合同。运输封装、分页和预算处理必须保留主 SQL 已有的选行及行序，不把有序子查询包进聚合后就宣称保序，也不解析 SQL 自行重建排序或在客户端重算；不能兑现时准确失败，不交付被重排、少行或截断的成功结果。
+
+请求中的 `ResultValueType.Scalar` 用可空的 `Integer precision/scale` 表达 SQL 类型容量；未指定时为 `null`，不使用负数哨兵，也不能擅自补成零。DECIMAL 必须给出正精度及 `0..precision` 内的小数位。插件明确处理这些可空字段，装载器按精确连接器 API 标识检查接口。
 
 HTTP 服务的分页、截断或未完成状态由插件识别；必须按明确的一致性合同取完或准确失败，不能把一页或已截断的数据当作完整结果返回。
 

package/server.example.json

@@ -15,7 +15,7 @@
       "subjects": ["replace-with-external-token-subject"],
       "scopes": ["olap.manage"],
       "operations": [
-        "describe-script-api", "execute-script", "describe-operation", "list-data-sources", "read-connector-capabilities", "inspect-warehouse", "candidate-values",
+        "describe-script-api", "execute-script", "wait-script", "cancel-script", "read-script-session", "reset-script-session", "close-script-session", "describe-operation", "list-data-sources", "read-connector-capabilities", "inspect-warehouse", "candidate-values",
         "read-governance", "write-governance", "register-source-dataset", "read-query-capability",
         "list-publications", "read-publication",
         "validate-query", "explain-query", "execute-query", "save-query", "update-query", "read-query", "list-queries", "read-deployment-availability",