@hanger-source/agentic-olap 0.11.3 → 0.13.1

package/licenses/jvm/dependencies.json

@@ -364,6 +364,22 @@
             
         ]
     },
+    {
+        "coordinate": "org.jetbrains.kotlin:kotlin-compiler-embeddable:2.2.21",
+        "jar": "kotlin-compiler-embeddable-2.2.21.jar",
+        "sha256": "9588fa696ac5507af764fd5660df6894185e12704ec1bc3f5cb772af4987f295",
+        "embeddedNotices": [
+            
+        ]
+    },
+    {
+        "coordinate": "org.jetbrains.kotlin:kotlin-daemon-embeddable:2.2.21",
+        "jar": "kotlin-daemon-embeddable-2.2.21.jar",
+        "sha256": "91c0673c22e44b054ae0314d323860ebe1f3aff3f0ebc74fff82c4733dde09be",
+        "embeddedNotices": [
+            
+        ]
+    },
     {
         "coordinate": "org.jetbrains.kotlin:kotlin-reflect:2.2.21",
         "jar": "kotlin-reflect-2.2.21.jar",
@@ -372,6 +388,54 @@
             
         ]
     },
+    {
+        "coordinate": "org.jetbrains.kotlin:kotlin-script-runtime:2.2.21",
+        "jar": "kotlin-script-runtime-2.2.21.jar",
+        "sha256": "2b1519b427b514d1536c1b425674b03fe914af637924028e9959c6625442df51",
+        "embeddedNotices": [
+            
+        ]
+    },
+    {
+        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-common:2.2.21",
+        "jar": "kotlin-scripting-common-2.2.21.jar",
+        "sha256": "414ed91c3f5e4492b23cb9537842b4651038e25dad84107939f434c2203f2a92",
+        "embeddedNotices": [
+            
+        ]
+    },
+    {
+        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-compiler-embeddable:2.2.21",
+        "jar": "kotlin-scripting-compiler-embeddable-2.2.21.jar",
+        "sha256": "d934b9d0c246bc09624b7068af58ad57cef11dbe2addbc7b19d250cce42de1c9",
+        "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",
+        "embeddedNotices": [
+            
+        ]
+    },
+    {
+        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-jvm-host:2.2.21",
+        "jar": "kotlin-scripting-jvm-host-2.2.21.jar",
+        "sha256": "ef72f73d752157c9a57e2a6e173a80be5304023b25caf86bd6b5b17cc5e37ada",
+        "embeddedNotices": [
+            
+        ]
+    },
+    {
+        "coordinate": "org.jetbrains.kotlin:kotlin-scripting-jvm:2.2.21",
+        "jar": "kotlin-scripting-jvm-2.2.21.jar",
+        "sha256": "83820c5fcc5d28f045f914ecd5900bbbcf8115b0d7007334de069fe6c70669e6",
+        "embeddedNotices": [
+            
+        ]
+    },
     {
         "coordinate": "org.jetbrains.kotlin:kotlin-stdlib:2.2.21",
         "jar": "kotlin-stdlib-2.2.21.jar",
@@ -380,6 +444,30 @@
             
         ]
     },
+    {
+        "coordinate": "org.jetbrains.kotlinx:kotlinx-coroutines-core-jvm:1.8.0",
+        "jar": "kotlinx-coroutines-core-jvm-1.8.0.jar",
+        "sha256": "9860906a1937490bf5f3b06d2f0e10ef451e65b95b269f22daf68a3d1f5065c5",
+        "embeddedNotices": [
+            
+        ]
+    },
+    {
+        "coordinate": "org.jetbrains.kotlinx:kotlinx-serialization-core-jvm:1.9.0",
+        "jar": "kotlinx-serialization-core-jvm-1.9.0.jar",
+        "sha256": "1f0afa172110e45a7231ef1b44ae8fd84c1ebaff96f3fc3ad68ef8c48120b59c",
+        "embeddedNotices": [
+            
+        ]
+    },
+    {
+        "coordinate": "org.jetbrains.kotlinx:kotlinx-serialization-json-jvm:1.9.0",
+        "jar": "kotlinx-serialization-json-jvm-1.9.0.jar",
+        "sha256": "d94cc34cae39246a1af74fda63f9c4812ce12216ef641d5fa3bbbb539a6922d8",
+        "embeddedNotices": [
+            
+        ]
+    },
     {
         "coordinate": "org.jetbrains:annotations:13.0",
         "jar": "annotations-13.0.jar",
@@ -436,6 +524,14 @@
             
         ]
     },
+    {
+        "coordinate": "org.slf4j:slf4j-api:2.0.18",
+        "jar": "slf4j-api-2.0.18.jar",
+        "sha256": "44508fd1576500688c790b190acdd16fec4f8c79a3e0b900afd70503cf055f55",
+        "embeddedNotices": [
+            "org.slf4j/slf4j-api/2.0.18/META-INF/LICENSE.txt"
+        ]
+    },
     {
         "coordinate": "org.slf4j:slf4j-api:2.0.19",
         "jar": "slf4j-api-2.0.19.jar",

package/licenses/jvm/org.slf4j/slf4j-api/2.0.18/META-INF/LICENSE.txt

@@ -0,0 +1,24 @@
+Copyright (c) 2004-2022 QOS.ch Sarl (Switzerland)
+All rights reserved.
+
+Permission is hereby granted, free  of charge, to any person obtaining
+a  copy  of this  software  and  associated  documentation files  (the
+"Software"), to  deal in  the Software without  restriction, including
+without limitation  the rights to  use, copy, modify,  merge, publish,
+distribute,  sublicense, and/or sell  copies of  the Software,  and to
+permit persons to whom the Software  is furnished to do so, subject to
+the following conditions:
+
+The  above  copyright  notice  and  this permission  notice  shall  be
+included in all copies or substantial portions of the Software.
+
+THE  SOFTWARE IS  PROVIDED  "AS  IS", WITHOUT  WARRANTY  OF ANY  KIND,
+EXPRESS OR  IMPLIED, INCLUDING  BUT NOT LIMITED  TO THE  WARRANTIES OF
+MERCHANTABILITY,    FITNESS    FOR    A   PARTICULAR    PURPOSE    AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE,  ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+

package/package.json

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

package/resources.json

@@ -1,21 +1,21 @@
 {
-  "connectorApiVersion": "agentic-olap-connector/v11-kotlin-native-collection-relations-calcite-1.42",
+  "connectorApiVersion": "agentic-olap-connector/v12-kotlin-native-collection-placement-calcite-1.42",
   "connectors": [
     "connectors/0001-h2/connector.json",
     "connectors/0002-duckdb/connector.json"
   ],
   "sdk": "sdk",
   "sdkArtifacts": {
-    "connector-api": "com.github.hanger-source.agentic-olap:connector-api:v0.11.3",
-    "connector-loader": "com.github.hanger-source.agentic-olap:connector-loader:v0.11.3",
-    "engine-core": "com.github.hanger-source.agentic-olap:engine-core:v0.11.3",
-    "execution-calcite": "com.github.hanger-source.agentic-olap:execution-calcite:v0.11.3",
-    "execution-catalog": "com.github.hanger-source.agentic-olap:execution-catalog:v0.11.3",
-    "olap-contracts": "com.github.hanger-source.agentic-olap:olap-contracts:v0.11.3",
-    "semantic-calcite": "com.github.hanger-source.agentic-olap:semantic-calcite:v0.11.3",
-    "warehouse-contracts": "com.github.hanger-source.agentic-olap:warehouse-contracts:v0.11.3",
-    "warehouse-jdbc": "com.github.hanger-source.agentic-olap:warehouse-jdbc:v0.11.3"
+    "connector-api": "com.github.hanger-source.agentic-olap:connector-api:v0.13.1",
+    "connector-loader": "com.github.hanger-source.agentic-olap:connector-loader:v0.13.1",
+    "engine-core": "com.github.hanger-source.agentic-olap:engine-core:v0.13.1",
+    "execution-calcite": "com.github.hanger-source.agentic-olap:execution-calcite:v0.13.1",
+    "execution-catalog": "com.github.hanger-source.agentic-olap:execution-catalog:v0.13.1",
+    "olap-contracts": "com.github.hanger-source.agentic-olap:olap-contracts:v0.13.1",
+    "semantic-calcite": "com.github.hanger-source.agentic-olap:semantic-calcite:v0.13.1",
+    "warehouse-contracts": "com.github.hanger-source.agentic-olap:warehouse-contracts:v0.13.1",
+    "warehouse-jdbc": "com.github.hanger-source.agentic-olap:warehouse-jdbc:v0.13.1"
   },
   "sdkRepository": "https://jitpack.io",
-  "version": "0.11.3"
+  "version": "0.13.1"
 }

package/sdk/API.md

@@ -2,7 +2,7 @@
 
 `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/v11-kotlin-native-collection-relations-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，不能把本地安装版本当作远程运行版本。
 
@@ -19,7 +19,7 @@ SDK 的 JAR、POM 由插件工程的 Gradle 从 JitPack 匿名取得，第三方
 ```json
 {
   "connectorRef": {"id": "backend", "version": "1.0.0", "sha256": "完整插件组摘要"},
-  "apiVersion": "agentic-olap-connector/v11-kotlin-native-collection-relations-calcite-1.42",
+  "apiVersion": "agentic-olap-connector/v12-kotlin-native-collection-placement-calcite-1.42",
   "jars": [
     {"file": "connector-backend.jar", "sha256": "该JAR摘要"},
     {"file": "backend-jdbc.jar", "sha256": "该JAR摘要"}
@@ -75,16 +75,23 @@ SDK 的 JAR、POM 由插件工程的 Gradle 从 JitPack 匿名取得，第三方
 
 集合结果、逐项展开、排序和文本显示分别声明 `COLLECTION_RESULTS/EXPANSION/SORT/TEXT` 能力。`sortCollection` 映射明确的方向及 NULL 顺序，`collectionText` 映射明确的分隔符与 NULL 替代；不能把数组提前解码成字符串代替这些运算。
 
-`expandCollection(collection,outputType,tableAlias)` 在 Rel 转 SQL 时接收当前输入行中已限定来源的 ARRAY 表达式和内核决定的完整输出类型。`collection` 可以直接是输入列引用，不附带读取该值的子查询。`outputType.fieldList` 依次声明完整元素、实际位置两列的名称和类型，保留 ROW 字段顺序、递归类型及 NULL 性质。返回 `CompilationSupport.CollectionExpansion(relation,element,ordinal)`：`relation` 为使用给定别名的原生 FROM AST，`element` 与 `ordinal` 为针对这条输入记录和展开关系的取值表达式。插件按后端语法在该关系中表达必要的 LATERAL；核心不额外强制包一层相关派生表。
+`expandCollection(outputType,tableAlias)` 在 Rel 转 SQL 时返回 `CompilationSupport.CollectionExpansion` 的原生放置计划。`outputType.fieldList` 依次声明完整元素、从 1 开始的位置两列的名称和类型，保留 ROW 字段顺序、递归类型及 NULL 性质。两种计划分别对应原生 FROM 与输入投影 SRF；精确插件在编译时明确选择，不在来源执行失败后切换。
 
-例如，支持数组下标的来源可以用表函数产生真实下标：`relation` 映射为 `GENERATE_SUBSCRIPTS(input.items,1) AS expanded(i)`，`element` 映射为 `input.items[expanded.i]`，`ordinal` 映射为 `expanded.i - ARRAY_LOWER(input.items,1) + 1` 并按所给整数类型定型。直接返回完整元素的来源也可以使用 `UNNEST(input.items) WITH ORDINALITY`。这说明映射所需的三部分，不宣称任意后端都支持示例语法或相关执行。
+- `CollectionExpansion.Relation(generate)`：核心将当前输入行的 ARRAY 引用交给 `generate`，取得 `CollectionRows(relation,element,ordinal)`。`relation` 是使用给定 `tableAlias` 的原生 FROM AST；核心构造 CROSS／LEFT JOIN、完整输入透传与输出投影。必要的表函数 LATERAL 语法由插件映射。
+- `CollectionExpansion.InputProjection(generate,values)`：核心在完整输入上添加恰好一个 `generate(array)` 返回的 SELECT-list SRF，并将生成值绑定为内部列；下一层调用 `values(array,generated)` 取得 `CollectionValues(element,ordinal)`。两个回调只使用各自拿到的当前作用域引用，不能捕获另一层的字段别名。原生生成值可以是下标或完整有类型值，不能将多个独立 SRF 放入同一生成表达式。
 
-内核拥有输入人口、输出投影和 INNER／OUTER：NULL 数组或空数组在 INNER 下无记录，在 OUTER 下补一个 NULL 元素及 NULL 序号；实际 NULL 元素有自己的非 NULL 序号，重复元素不丢弃。序号从 1 开始，不直接暴露可能具有其他下界的原生数组下标；`ordinal` 必须在实际元素上非 NULL，并在 OUTER 无匹配时保持 NULL。核心据此为 OUTER 的元素投影补整个 NULL，避免重建 ROW 时制造“成员全 NULL 的非空 ROW”。原生展开扁平化 ROW 字段时，插件仍须保留或重建完整元素，不能仅凭所有成员为 NULL 判断整个 ROW 为 NULL。映射不得自行过滤、去重、归约或扩大输入人口，无法兑现的形态应明确拒绝。
+例如，位置生成器的原生下标可由插件映射为 `element=array[index]`，`ordinal=index-array_lower(array,1)+1` 并按输出整数类型定型。FROM 表函数和 SELECT-list SRF 的放置由各自计划表达；插件不需要解析核心别名、取得完整输入关系、复制聚合或改写生成后的 SQL。原生类型、下标取值与数组下界由插件负责，不宣称任意后端都具有相同语法或能力。
+
+内核拥有输入人口、输出投影和 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 验收。
 
 `ROW_FIELD` 的逻辑字段索引仍由内核验证。需要原生匿名字段名或专用字段运算的插件，可以在 `SqlDialect.prepareUnparse(RexNode)` 处理 `RexFieldAccess`：此时保有 `referenceExpr.type`、`field.index` 和结果类型，再转换为插件自己的有类型 Rex 调用及 SQL AST。不要等普通 SQL 标识符已经生成后解析 `EXPR$N`，也不能把逻辑字段名普遍替换成某个后端的 `fN`。
 
 `textIdentityEquals(builder,left,right)` 返回两个真实文本操作数的完整精确身份 BOOLEAN 比较，保留 NULL 三值逻辑，不要求产生二进制中间值。原生等号只有在插件能够兑现类型、编码及 collation 的适用保证时才可直接使用。后端是否保留 HashJoin、过滤下推及运行时过滤，由实际执行计划确认；此映射不授予插件改写业务人口、LEFT 补空或重复度的权限。
 
+插件构造原生 Rex 函数时，应通过 Calcite 的正式运算符合同如实披露 NULL 传播。仅声明可空返回类型不足以证明输入 NULL 时结果必为 NULL；严格传播且非 NULL 输入不产生 NULL 的函数可通过 `SqlOperator.getStrongPolicyInference()` 返回 `Strong.Policy.ANY`。内置 DuckDB `ENCODE`、H2 `RAWTOHEX/STRINGTOUTF8` 按实际编码函数语义声明这一性质，SQL 与精确身份比较保持原样。核心据此分析过滤条件排除 NULL 的事实；函数语义未知或证明不完整时，保留运行关系检查，不能用声明跳过人口、NULL、重复度或数量保证。
+
 lowering 结果在本次计算内持有与精确引用对应的同一编译支持，结果转换显式使用该支持；它不写入发布、JSON 或另一份原生类型表。连接器不能用不透明业务 SQL 替换完整查询。
 
 `JdbcSupport` 在明确调用时取得连接描述与凭据，拥有只读连接、原生内存配置、快照建立、元数据约束、封存锚点、参数绑定及标量解码。`arrayElement(Array, ResultSet)` 解码已定位的实际数组元素；规范 JDBC 实现可复用第2列的元数据，缺少该元数据的原生游标由插件明确解码。共同物化器保留递归容器和共享预算，不将元素转成文本。普通在线源无需宣称封存能力。连接和语句由实际调用方关闭，取消沿 `WarehouseExecutionControl` 传递；插件关闭时注销自己装载的驱动。`warehouse-jdbc` 的标准支持代码可复用，具体后端插件不依赖 `semantic-calcite` 内部实现。

package/sdk/SOURCE-ACCESS.md

@@ -2,7 +2,7 @@
 
 完整 MCP 服务通过来源插件访问数据。使用方提供与其网络、鉴权和查询协议相符的插件，服务负责语义管理、发布、规划、SQL 生成、执行要求检查及结果合同校验。HTTP 查询服务是来源访问实现，不需要数据库端口、JDBC URL、数据库凭据或 catalog 权限。业务公式、资格规则和指标组合仍通过语义定义和 Query 表达。
 
-本文描述源码中的来源访问合同：连接器 API 为 `agentic-olap-connector/v11-kotlin-native-collection-relations-calcite-1.42`，元数据存储格式为 `15`。服务、SDK 与插件须来自同一发行或同轮源码构建，安装发行物时以该发行声明及实际服务合同为准。旧存储格式明确拒绝，服务不会自动改写已有持久根。
+本文描述源码中的来源访问合同：连接器 API 为 `agentic-olap-connector/v12-kotlin-native-collection-placement-calcite-1.42`，元数据存储格式为 `16`。服务、SDK 与插件须来自同一发行或同轮源码构建，安装发行物时以该发行声明及实际服务合同为准。旧存储格式明确拒绝，服务不会自动改写已有持久根。
 
 ## 配置来源
 
@@ -26,7 +26,7 @@
 
 `dataSourceId` 是稳定业务来源身份；`SourceBindingRef={dataSourceId,sourceIdentityHash}` 标识一份不可变访问绑定。摘要由来源 ID、精确插件引用、方言、规范化身份参数和凭据槽名共同形成，不包括运行参数、凭据值与保存凭据的环境变量名。运行参数只能改变预算、等待或诊断行为，不能改变数据选择、类型、文本比较或计算口径；超限须明确失败，不能截断为成功。改变插件、端点或其他身份参数产生不同摘要。同一来源 ID 可以部署多个不同绑定；同一绑定不能同时配置两套运行策略。
 
-Agent 从 `list-data-sources` 取得获授权的 `dataSourceId/sourceIdentityHash/connectorRef/dialectId/accessCapabilities`，按本次业务用途明确选择绑定，不按列表顺序、唯一性猜测或“最新”选择。调查与结构登记均提交返回的精确 `sourceIdentityHash`。该摘要不是数据库内容快照或结构版本。
+Agent 从 `olap.sources.list(EmptyRequest)` 取得获授权的 `binding/connectorRef/dialectId/accessCapabilities`，按本次业务用途明确选择绑定，不按列表顺序、唯一性猜测或“最新”选择。调查与结构登记均提交返回的精确 `sourceIdentityHash`。该摘要不是数据库内容快照或结构版本。
 
 JDBC 实现的 `identityParameters` 为 `jdbcUrl`、可选 `username` 和 `driverClassName`，`runtimeParameters` 为 `{}`，凭据槽为可选 `password`。这些字段只由 JDBC 插件解释。HTTP 插件不填写虚假的 JDBC 字段。
 
@@ -34,10 +34,10 @@ JDBC 实现的 `identityParameters` 为 `jdbcUrl`、可选 `username` 和 `drive
 
 结构获取与 SQL 执行分开。两种结构供应方式都进入相同的物理定义、语义建设和发布流程：
 
-- 使用方显式提供结构：通过 MCP `describe-governance-command` 读取 `register-source-structure` 的准确输入，再通过 `write-governance` 调用该命令。输入包括已授权 `dataSourceId/sourceIdentityHash`、catalog/schema 范围、`authority`、`revision`、表、字段、SQL 类型及约束声明，以及认证主体对应的 `requestedBy`。不需要先调用 `discover-source`。
-- 插件提供结构：实现 `SourceAccess.discover`，从数据库 catalog、使用方配置或外部目录取得结构。`discover-source` 同样提交精确 `dataSourceId/sourceIdentityHash`，仅对声明支持调查的来源调用该实现。通过 `inspect-warehouse` 调查时，除读取调查能力合同外，内部 payload 也须携带这两个字段。
+- 使用方显式提供结构：通过 `describe-script-api` 读取 `register-source-structure` 对应方法和 `SourceStructureRegistrationRequest` 的正式构造器，再在 kts 中调用 `olap.governance.registerSourceStructure`。输入包括已授权 `dataSourceId/sourceIdentityHash`、catalog/schema 范围、`authority`、`revision`、表、字段、SQL 类型及约束声明，以及 `requestedBy=olap.caller.subject`。不需要先调用 `discover-source`。
+- 插件提供结构：实现 `SourceAccess.discover`，从数据库 catalog、使用方配置或外部目录取得结构。`discover-source` 同样提交精确 `dataSourceId/sourceIdentityHash`，仅对声明支持调查的来源调用该实现。通过 `olap.sources.inspect` 调查时，除读取能力变体外，其余正式请求均持有精确 `SourceBindingRef`。
 
-`register-source-structure` 返回保存后的 snapshot、tables 和 columns。随后按 `create-physical-table` 的合同选择该 `discoveredTableId`，完整治理字段，再建立逻辑、指标及其他可组合定义，采用并发布。`list-source-discoveries`、`read-source-discovery` 和列读取返回已保存的结构，读取它们不触发数据库探测。
+`olap.governance.registerSourceStructure` 返回 `SourceDiscoveryReceipt`，给出实际保存的 `snapshotId`、状态和表、列计数。用该引用调用 `olap.semantics.sourceDiscovery`、`discoveredTables` 和 `discoveredColumns` 读取已保存结构，再以实际 `discoveredTableId` 构造物理定义，继续建设、采用并发布其他语义。读取已保存结构不触发数据库探测。
 
 同一物理表身份的新版本可以显式采用同一稳定业务来源的另一访问绑定，但必须通过该绑定的结构证据建立，不覆盖旧版本。发布冻结所采用的精确绑定；新部署可以同时保留旧、新绑定。执行旧发布时，旧绑定必须仍在本次部署中；缺失返回 `SOURCE_BINDING_NOT_DEPLOYED`，不自动改用同 ID 的另一绑定。切换当前业务使用的访问绑定，需要明确修订采用及其依赖并发布，再由调用者选择该精确发布。
 
@@ -47,6 +47,8 @@ JDBC 实现的 `identityParameters` 为 `jdbcUrl`、可选 `username` 和 `drive
 
 约束声明不等于约束已核验。规划或执行实际依赖键、关系检查、封存集合等保证时，来源必须兑现对应要求。结构供应者负责及时登记变化并修订、发布受影响定义；显式结构不会被服务偷偷替换成一次数据库调查结果。
 
+冻结列的非空声明进入原生类型系统时，核心记录对应精确来源列的 `NOT_NULL` 采用；声明本身不代替核验。执行者必须在与主查询一致的读基础中检查真实数据，发现 NULL 返回 `SOURCE_NOT_NULL_VIOLATION`；最终输出没有保留该列、或 NULL 已被聚合隐藏时也不能省略。原本可空的列由查询内过滤证明非空，不因此增加来源非空保证。仅作为原生函数参数的表不采用行字段的非空保证；同时实际读取其数据行时按真实列用途记录。JDBC 的数据非空见证不要求读取 catalog 约束，PK／UK 等命名约束仍按插件明确兑现的 catalog／数据一致性核验。
+
 字段必须明确提供类型、顺序与可空性。`autoIncrement/generated` 可以缺省并保存为未知；它们不决定读取查询的保证。主键列必须明确声明为不可空，约束引用必须属于已声明字段。查询返回头可以提供类型信息，但不能替代基础表的键与非空声明；服务不会从样本中推导这些保证。
 
 ## 实现插件
@@ -79,29 +81,39 @@ JDBC 实现的 `identityParameters` 为 `jdbcUrl`、可选 `username` 和 `drive
 
 精确 AVG 的原生结果由连接器 `typeSystem.deriveAvgAggType`、`nativeAggregate` 和 `decimalAverageRounding` 如实声明，核心再处理最终业务结果的 DECIMAL 容量和舍入。作者指定最终精度不能补救原生聚合已丢失的信息。原生类型推导明确拒绝时返回 `NATIVE_AGGREGATE_MAPPING_UNAVAILABLE` 和实际输入类型；插件实现者应先研究真实后端映射，不能用浮点、客户端舍入或未经证明的 SUM/COUNT 改写替代。
 
-作者通过 `describe-operation` 选择 `read-connector-capabilities` 读取输入合同，再向该操作提交类型化聚合查询。例如，对已经获准的精确连接器查询 BIGINT 的全局 AVG：
+作者通过 `describe-script-api` 读取 `read-connector-capabilities` 的方法和正式参数，再在脚本中提交具体聚合查询。例如，以下程序使用已获准来源所指的精确连接器读取 BIGINT 全局 AVG 映射：
 
-```json
-{
-  "aggregate": {
-    "connectorRef": {"id": "<获准连接器ID>", "version": "<精确版本>", "sha256": "<精确摘要>"},
-    "aggregation": "AVG",
-    "inputType": {"name": "BIGINT", "precision": null, "scale": null, "nullable": true},
-    "grouped": false
-  }
+~~~kotlin
+import com.olap.prototype.contract.NativeValueType
+
+val selected = olap.sources.list(EmptyRequest).items.single {
+    it.binding.dataSourceId == parameters.text("dataSourceId") &&
+        it.binding.sourceIdentityHash == parameters.text("sourceIdentityHash")
 }
-```
+olap.output(olap.sources.connectorCapabilities(
+    ConnectorCapabilitiesRequest(
+        aggregate = ConnectorCapabilitiesRequest.Aggregate(
+            connectorRef = selected.connectorRef,
+            aggregation = ResultAggregation.Kind.AVG,
+            inputType = NativeValueType("BIGINT", null, null, nullable = true),
+            grouped = false
+        )
+    )
+))
+~~~
 
 `aggregation` 使用正式聚合枚举；`inputType` 是传入聚合的表达式原生类型，包含实际可空性和完整容量，不是最终业务结果合同。DECIMAL 必须指定 precision、scale，有长度的文本必须指定 precision；类型或容量不能被后端类型工厂静默改写。`grouped=false` 表示没有分组键的全局聚合，`true` 表示存在普通分组键；分组集合中的空分组按全局方式查询。该上下文用于原生结果可空性推导。
 
 响应的 `aggregate.mapping` 为 `MAPPED` 时给出 `resultType` 和 `aggregationRounding`；AVG 使用实际类型系统、原生聚合函数及舍入声明，二者容量不一致时明确拒绝。浮点 AVG 的 aggregationRounding 为 NONE，非 AVG 也为 NONE。`UNAVAILABLE` 携带 `NATIVE_AGGREGATE_MAPPING_UNAVAILABLE`，表示插件没有为该类型兑现映射；不会返回推测的容量或舍入。精确连接器必须用于本主体获准的来源，不能借此读取任意已安装插件。
 
-读取不连接数据源、不执行 SQL，披露的是精确插件的编译声明，不验证后端实际版本、连接状态或完整 Query。`MAPPED` 不代替单位、算术保证、NULL、溢出和最终结果容量检查。数值 AVG 的 `valueContract` 仍为必填；作者明确填写的 `aggregationRounding` 必须匹配原生策略，`valueContract.result.rounding` 仅负责额外的最终输出舍入。原 SQL 没有 ROUND，不能据此把原生策略填为 NONE；插件也不能用未经核实的统一舍入值宣称支持。
+读取不连接数据源、不执行 SQL，披露的是精确插件的编译声明，不验证后端实际版本、连接状态或完整 Query。`MAPPED` 不代替单位、算术保证、NULL、溢出和最终结果容量检查。数值 AVG 的 `valueContract` 仍为必填；事实度量的 `aggregationRounding`、完成关系中 `ResultAggregation.Average.rounding` 都须明确接受相应原生策略，`valueContract.result.rounding` 仅负责额外的最终输出舍入。原 SQL 没有 ROUND，不能据此把原生策略填为 NONE；插件也不能用未经核实的统一舍入值宣称支持。
 
-`expandCollection` 接收当前输入行的类型化数组表达式，返回原生展开关系、完整元素和序号三部分 SQL AST。核心拥有逐行人口、INNER／OUTER 及输出投影，不强制相关派生表形状；插件可以直接映射表函数或下标生成。序号从 1 开始，实际 NULL 元素仍有位置，OUTER 缺行则元素与序号均为 NULL。完整接口与原生映射范式见[连接器 API](API.md)。一种原生常量展开成功，不代表同一后端已支持真实输入行或聚合结果的相关展开。
+`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 的验收。
 
 `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、人口、重复度与数量边界。
+
 连接器若能保证受支持操作数的原生相等与精确身份相等一致，可以在核验实际类型后返回 `builder.equals(left,right)`。该保证需要覆盖列、参数与表达式的比较行为，包括 NULL、大小写、尾空格和 Unicode；不能仅根据数据库默认 collation 推定。类型或条件超出保证范围时明确拒绝。CHAR 等可能改变空格含义的类型必须单独处理，不能通过类型标签或有损 CAST 冒充等价。
 
 原生候选等号与精确残余同时出现，并不保证后端能够执行原生 HashJoin 或运行时过滤。核心不自动删除残余、移到 WHERE，或插入额外人口裁剪。来源原生运算由插件兑现；关系规划的新增规则需要独立证明 LEFT 未匹配人口、bag 重复度、NULL 和求值作用域均保持，并由实际计划确认收益。不能将某个后端的规划限制变成所有使用者必须配置的业务规则。
@@ -110,11 +122,11 @@ JDBC 实现的 `identityParameters` 为 `jdbcUrl`、可选 `username` 和 `drive
 
 ## 调用原生标量函数
 
-通过 `read-connector-capabilities` 的空 payload 读取当前主体可访问来源所用的精确连接器；响应的 `connectors` 每项包含 `connectorRef`、`nativeScalarFunctions`、`compilationCapabilities`、`parameterSubmission` 和 `configurationParameters`。这些是精确插件的声明，不连接来源或证明完整查询可用。函数声明给出 `id`、有序 `parameters`、`resultType`、`arithmetic` 和 `stability`，不按 SQL 方言或产品名称猜函数。
+通过 `olap.sources.connectorCapabilities(ConnectorCapabilitiesRequest(aggregate=null))` 读取当前主体可访问来源所用的精确连接器；响应的 `connectors` 每项包含 `connectorRef`、`nativeScalarFunctions`、`compilationCapabilities`、`parameterSubmission` 和 `configurationParameters`。这些是精确插件的声明，不连接来源或证明完整查询可用。函数声明给出 `id`、有序 `parameters`、`resultType`、`arithmetic` 和 `stability`，不按 SQL 方言或产品名称猜函数。
 
 `compilationCapabilities` 只列出插件明确支持的编译能力。`CORRELATED_DERIVED_PROJECTION` 表示派生关系投影可以引用外层查询值，普通 EXISTS 的条件相关不需要这项能力。若数值求值绑定实际需要这种投影而插件未声明，编译在提交 SQL 前返回 `NATIVE_COMPILATION_CAPABILITY_MISSING`，并指出 `capability=CORRELATED_DERIVED_PROJECTION`、`operation=NUMERIC_EVALUATION_BINDING`。不退回重复内联、移除人口守卫或提前计算未选中分支。
 
-`NATIVE_CALL` 表达式提交精确 `connectorRef`、`function` 和有序 `arguments`。`SCALAR` 参数为 `{kind:"SCALAR",expression:完整标量表达式}`；`PHYSICAL_TABLE` 参数为 `{kind:"PHYSICAL_TABLE",physicalTableId,physicalTableVersion}`。物理表参数引用已采用的精确版本，必须与调用所在来源的绑定、插件及方言一致，作为真实来源依赖冻结和核验。Query 内联调用只能引用本次精确发布允许的表闭包；它不是表名文本，也不接受任意 SQL。实际参数形状从表达式合同读取。技术调查 `profile-relationship` 不提供已采用表解析，不支持 `NATIVE_CALL`。
+`SemanticExpression.NativeCall` 提交精确 `connectorRef`、`function` 和有序 `arguments`。参数使用正式 Scalar 与 PhysicalTable 变体，分别持有完整表达式或精确物理表身份和版本。物理表参数引用已采用的精确版本，必须与调用所在来源的绑定、插件及方言一致，作为真实来源依赖冻结和核验。Query 内联调用只能引用本次精确发布允许的表闭包；它不是表名文本，也不接受任意 SQL。实际 Kotlin 构造器与封闭变体从服务 API 发现读取。技术调查 `profile-relationship` 不提供已采用表解析，不支持 `NATIVE_CALL`。
 
 调用保留在本次来源 SQL 中执行。来源要求通过 `uses` 明确区分 `ROWS`（读取数据行）与 `NATIVE_TABLE`（原生函数的表参数）；两者都核对精确来源身份与授权，行约束及有限集合核验按实际 `ROWS` 用途要求。仅作函数参数的表也进入依赖闭包，无需伪造字段引用。
 
@@ -142,7 +154,7 @@ HTTP 服务的分页、截断或未完成状态由插件识别；必须按明确
 
 `readBasis` 为 `Unknown(reason)` 或 `Versioned(authority,version,partitions,pinning)`，描述本次实际读取的数据基础。结构 snapshot、schemaHash、访问绑定及定义版本均不替代它。动态函数仍在同一 SQL 内求值；插件不能事前另查一个分区值，再宣称它就是该 SQL 实际采用的值。不能取得完整读基础时如实返回 Unknown。
 
-保存结果可以按精确引用回读，不要求来源再次执行。按保存查询重新执行会建立新运行，默认读取当时数据。只有来源能强制使用指定版本时才声明 `PINNED_READ`，并接受 `SourceSqlRequest.expectedReadBasis`；核心核验返回读基础与请求完全一致，不自动换成最新。`execute-query.readBasis` 使用已知的 VERSIONED 基础；不支持 pin、版本已不可用或实际基础不符时准确拒绝。可 pin 不等于历史版本永久保留，也不意味着任意动态“最新”查询已可重放。
+保存结果可以按精确引用回读，不要求来源再次执行。按保存查询重新执行会建立新运行，默认读取当时数据。只有来源能强制使用指定版本时才声明 `PINNED_READ`，并接受 `SourceSqlRequest.expectedReadBasis`；核心核验返回读基础与请求完全一致，不自动换成最新。`QueryExecutionRequest.readBasis` 使用已知的 Versioned 基础；不支持 pin、版本已不可用或实际基础不符时准确拒绝。可 pin 不等于历史版本永久保留，也不意味着任意动态“最新”查询已可重放。
 
 一次完整计算要求同一精确 `SourceBindingRef`、方言和连接器。跨绑定的输入在编译时返回 `SOURCE_BINDING_CONFLICT` 及具体作用域和来源引用。保存结果是读取交付物，当前没有把结果引用重新导入为 Query 输入的入口；需要物化时由外部系统维护真实来源，并通过正常结构与语义登记采用。产品不隐式联邦查询或客户端重算。
 

package/server.example.json

@@ -15,10 +15,9 @@
       "subjects": ["replace-with-external-token-subject"],
       "scopes": ["olap.manage"],
       "operations": [
-        "describe-operation", "list-data-sources", "read-connector-capabilities", "inspect-warehouse", "candidate-values",
-        "discover-governance-reads", "describe-governance-read",
-        "read-governance", "discover-governance-commands", "describe-governance-command", "write-governance",
-        "list-publications", "read-publication", "search-semantics", "read-semantic-catalog", "read-semantic-asset", "read-semantic-definition", "read-query-language-contract", "read-semantic-expression-contract",
+        "describe-script-api", "execute-script", "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",
         "read-query-result", "read-query-result-metadata", "read-query-result-value", "profile-query-result",
         "search-query-usage", "read-query-usage", "append-query-usage-note"
@@ -32,6 +31,7 @@
   "dataRoot": "/var/lib/agentic-olap",
   "connectors": [],
   "dataSources": [],
+  "scripting": {"workerCount": 2, "jvmHeapMiB": 768, "maxCalls": 100, "nativeLogBytes": 1048576},
   "limits": {
     "requestSeconds": 120.0,
     "startupSeconds": 60.0,