@hanger-source/agentic-olap 0.14.0 → 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.0",
+  "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.0",
-    "connector-loader": "com.github.hanger-source.agentic-olap:connector-loader:v0.14.0",
-    "engine-core": "com.github.hanger-source.agentic-olap:engine-core:v0.14.0",
-    "execution-calcite": "com.github.hanger-source.agentic-olap:execution-calcite:v0.14.0",
-    "execution-catalog": "com.github.hanger-source.agentic-olap:execution-catalog:v0.14.0",
-    "olap-contracts": "com.github.hanger-source.agentic-olap:olap-contracts:v0.14.0",
-    "semantic-calcite": "com.github.hanger-source.agentic-olap:semantic-calcite:v0.14.0",
-    "warehouse-contracts": "com.github.hanger-source.agentic-olap:warehouse-contracts:v0.14.0",
-    "warehouse-jdbc": "com.github.hanger-source.agentic-olap:warehouse-jdbc:v0.14.0"
+    "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.0"
+  "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`。
@@ -41,6 +43,12 @@ SDK 的 JAR、POM 由插件工程的 Gradle 从 JitPack 匿名取得，第三方
 
 `nativeAggregate(SqlKind)` 返回该精确来源的 `SqlAggFunction`，包括真实返回类型推导。核心将已定义的聚合映射为原生 kind，并继续组织 DISTINCT、分组、窗口和数量保证；插件不接收业务指标公式。不支持的 kind 明确拒绝。例如 `STDDEV_SAMP` 的返回类型由该来源实现声明，不能由共同编译器统一假定为 DOUBLE。
 
+AVG 的类型容量、算术正确性与舍入必须共同成立。`typeSystem.deriveAvgAggType` 与 `nativeAggregate(AVG)` 的类型推导须一致；`decimalAverageRounding` 声明原生精确结果的舍入，作者的最终 DECIMAL 合同只控制后续输出。原生累加或除法若已静默产生错误，错误值仍可能落在合法输出容量内，`Overflow.FAIL` 的结果范围检查不能据此检测或修复该错误。插件不得将这种实现声明为可接受的精确 AVG，也不得改成原生浮点、猜一个 DECIMAL 或自动替换为 SUM/COUNT。
+
+现有 SPI 适用于能为其接受的原生输入类型和支持的执行形态给出统一、可兑现合同的策略。声明需涵盖实际参与行数、分组／窗口、NULL 及原生运算的中间容量；不能仅以少量小值、一个常量执行路径或最终结果类型作为依据。同一类型在不同执行形态上显示不同 scale 时，先区分无损表示差异与已经发生的原生舍入；单纯增大声明 precision／scale 不能恢复丢失的位数。若插件提供已证明的原生输入转换或另一原生聚合映射，必须在 SQL AST 映射及类型推导中一致表达，并保持原人口、权重及错误行为；这不是执行失败后切换的备选路径。
+
+`deriveAvgAggType` 接收的是输入技术类型，不接收本次数据的最小值、最大值或行数；发现请求中的 `inputType` 也不是业务值域证明。最终数量容量及 `Approximate.minimum/maximum` 不能充当 AVG 的受限输入合同。当前没有从样本、字段名或过滤文本自动推导“安全评分范围”的机制。仅当来源先给出明确可证明的受限策略、而现有正式表达仍无法承载其前提时，才有依据讨论相应扩展；保证未知时保持拒绝。
+
 只读属性 `CompilationSupport.parameterSubmission` 必须明确声明 `BIND_PARAMETERS` 或 `TYPED_LITERALS`。前者保留有序参数，后者通过 `parameterLiteral` 将已校验值映射成 SQL AST 字面量并保留编译类型 CAST；共同默认映射覆盖参数编码中的精确数值、文本、布尔与时间值，后端特殊映射由插件明确实现。主查询、关系检查和候选值均使用该选择，不做问号文本替换或运行失败后的自动切换。
 
 `CORRELATED_DERIVED_PROJECTION` 声明派生关系的投影能引用外层查询值。普通 `EXISTS` 条件相关不要求这项能力；数量合同的行内求值槽若必须把外层人口条件绑定在派生投影中，则按本次实际构造检查。缺失时在提交 SQL 前抛出 `NativeCompilationCapabilityException`，公开错误 `NATIVE_COMPILATION_CAPABILITY_MISSING` 包含 `capability` 与 `operation=NUMERIC_EVALUATION_BINDING`。插件依据真实后端行为声明，它不代表来源事务或快照能力。内核不删除人口保护、不重复内联检查，也不在执行失败后切换方案。DuckDB 声明此能力；当前 H2 不声明。
@@ -71,7 +79,13 @@ SDK 的 JAR、POM 由插件工程的 Gradle 从 JitPack 匿名取得，第三方
 
 `readBasis` 如实为 Unknown 或 Versioned；来源支持强制精确数据版本时才声明 PINNED_READ 并落实 `SourceSqlRequest.expectedReadBasis`。返回基础必须与要求相符，不能忽略 pin 后读取最新。分区名或访问绑定本身不证明内容不可变，也不保证历史版本永远可用。
 
-`SourceAccess.supportsConstraintVerification` 表达对冻结证据的约束核验能力。访问层的 `CONSISTENT_READ` 表达检查与计算针对一致数据状态成立，具体可以使用事务快照、原子 SQL 或不可变数据版本；不把 `TRANSACTION_SNAPSHOT` 作为所有实现的前置。声明能力不能替代实际执行每项必需检查，空结果也不能吞掉保证失败。
+`SourceAccess.supportsConstraintVerification` 是不连接来源的纯能力声明，用于决定是否向优化器提供冻结键等约束。返回 false 不会把真实非空列改为可空：冻结非空类型进入 Calcite 时仍产生精确列的 `NOT_NULL` 采用，即使只是单表 RAW_BAG 投影。`SourceSqlRequest.sourceRequirements` 给出精确绑定、表版本、表坐标、实际列类型与 `constraintUses`；`NOT_NULL.name` 是列名，其他项引用冻结键或规则。插件不解析 SQL 猜测检查对象，也不能仅凭业务 EventIdentity 推断检查范围。
+
+`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)。
+
+主 SQL 拥有最终结果的选行与行序语义，`SourceSqlRequest` 不另行提供排序键；`aliasMapping/outputTypes` 只是列合同。访问实现按来源返回顺序构造 `ResultFrame.rows`，运输、分页或预算处理不改变已有选行、重复度和排序。窗口排序、TopN 选行或集合内部排序不自动给出最终展示顺序；主 SQL 未给最终排序时不承诺稳定行序，并列键未区分的行也不额外确定顺序。不能仅凭有序子查询的样本认定外层 ARRAY／聚合会保序，也不能解析主 SQL 重建查询或在客户端重排来代替来源保证。
 
 集合结果、逐项展开、排序和文本显示分别声明 `COLLECTION_RESULTS/EXPANSION/SORT/TEXT` 能力。`sortCollection` 映射明确的方向及 NULL 顺序，`collectionText` 映射明确的分隔符与 NULL 替代；不能把数组提前解码成字符串代替这些运算。
 
@@ -84,7 +98,7 @@ SDK 的 JAR、POM 由插件工程的 Gradle 从 JitPack 匿名取得，第三方
 
 内核拥有输入人口、输出投影和 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 改写来掩盖来源错误。
 
@@ -115,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)。旧存储格式明确拒绝，服务不会自动改写已有持久根。
 
 ## 配置来源
 
@@ -47,7 +47,9 @@ JDBC 实现的 `identityParameters` 为 `jdbcUrl`、可选 `username` 和 `drive
 
 约束声明不等于约束已核验。规划或执行实际依赖键、关系检查、封存集合等保证时，来源必须兑现对应要求。结构供应者负责及时登记变化并修订、发布受影响定义；显式结构不会被服务偷偷替换成一次数据库调查结果。
 
-冻结列的非空声明进入原生类型系统时，核心记录对应精确来源列的 `NOT_NULL` 采用；声明本身不代替核验。执行者必须在与主查询一致的读基础中检查真实数据，发现 NULL 返回 `SOURCE_NOT_NULL_VIOLATION`；最终输出没有保留该列、或 NULL 已被聚合隐藏时也不能省略。原本可空的列由查询内过滤证明非空，不因此增加来源非空保证。仅作为原生函数参数的表不采用行字段的非空保证；同时实际读取其数据行时按真实列用途记录。JDBC 的数据非空见证不要求读取 catalog 约束，PK／UK 等命名约束仍按插件明确兑现的 catalog／数据一致性核验。
+冻结列的非空声明进入原生类型系统时，核心记录对应精确来源列的 `NOT_NULL` 采用；声明本身不代替核验。非空类型可以参与过滤简化与表达式推导，因此单表 `RAW_BAG` 原样读取也可能要求 `CONSTRAINT_VERIFICATION` 和 `CONSISTENT_READ`，不以 JOIN、聚合或唯一键归约为前提。实际采用范围来自本次冻结来源列及编译读取的元数据，不能按 EventIdentity 或主键字段猜测。
+
+执行者必须兑现每项采用的非空保证，最终输出没有保留该列、主查询为空或 NULL 已被聚合隐藏都不能免除要求。可以在与主查询一致的数据状态上检查真实数据，也可以在本次执行期间稳定的 schema 下，核验源端真实强制、覆盖所有被读取数据的非空约束；后一路径的条件见下文。原本可空的列由查询内过滤证明非空，不因此增加来源非空保证。仅作为原生函数参数的表不采用行字段的非空保证；同时实际读取其数据行时按真实列用途记录。内置 JDBC 实现采用数据非空见证，不要求读取 catalog 的非空约束；PK／UK 等命名约束仍按插件明确兑现的 catalog／数据一致性核验。
 
 字段必须明确提供类型、顺序与可空性。`autoIncrement/generated` 可以缺省并保存为未知；它们不决定读取查询的保证。主键列必须明确声明为不可空，约束引用必须属于已声明字段。查询返回头可以提供类型信息，但不能替代基础表的键与非空声明；服务不会从样本中推导这些保证。
 
@@ -67,13 +69,23 @@ JDBC 实现的 `identityParameters` 为 `jdbcUrl`、可选 `username` 和 `drive
 | --- | --- |
 | `validateConfiguration` | 校验自身参数与凭据槽；不把数据库探测作为通用前置 |
 | `capabilities` | 按实际配置声明独立能力 |
-| `supportsConstraintVerification` | 声明实现能为哪些冻结证据提供约束核验，供规划采用键；不连接来源。本次配置能力及实际保证仍在执行时核验 |
+| `supportsConstraintVerification` | 纯声明能否兑现交给优化器的冻结键等约束，不连接来源；返回 false 不会改变真实列的非空类型，也不免除本次 `NOT_NULL` 要求 |
 | `execute` | 执行核心给出的 `SourceSqlRequest`，兑现 SQL、参数、关系检查、来源保证和本次资源要求 |
 | `discover` / `snapshot` / `describe` | 可选结构供应或调查；没有实现时准确拒绝对应操作 |
 | `preview` / `profile` / `profileRelationship` | 可选样本、列和关系调查；分别按能力检查 |
 | `verifySealedDataset` | 只有支持封存来源核验时实现 |
 
-执行请求包含 SQL、无损类型参数、结果别名和输出类型，以及实际依赖的来源证据、约束和关系检查。插件不能丢弃附带检查后只执行主 SQL。存在关系检查或采用约束时，`CONSISTENT_READ` 要求检查与本次计算针对一致的数据状态成立；事务快照、同一原子 SQL 内检查或精确绑定的不可变数据版本，都可以兑现该要求。一次 HTTP 请求、一个 SQL 批次或“先检查再查询”本身不能证明一致性。插件负责落实其实际机制，并且即使主查询没有结果，也不能省略必须执行的保证检查。插件不认识或无法兑现的要求应明确拒绝，不改写业务语义。
+执行请求包含 SQL、无损类型参数、结果别名和输出类型，以及实际依赖的来源证据、约束和关系检查。插件不能丢弃附带检查后只执行主 SQL。存在关系检查或采用约束时，`CONSISTENT_READ` 要求检查与本次计算针对一致的数据状态成立；事务快照、同一原子 statement 内检查或精确绑定的不可变数据版本，都可以兑现该要求。一次 HTTP 请求、一个 SQL 批次或“先检查再查询”本身不能证明一致性。插件不认识或无法兑现的要求应明确拒绝，不改写业务语义。
+
+`sourceRequirements` 已携带 `dataSourceId`、精确 `connectorRef`、`physicalTableId/physicalTableVersion`、实际表坐标、冻结 `evidence`、本次采用的 `columns` 与 `constraintUses`。`NOT_NULL.name` 直接标识列，其他约束项定位冻结证据中的实际键或规则，插件无需解析 SQL 猜测来源列。`relationChecks` 另行给出 SQL、类型参数与违例码。两者都属于执行合同，参数顺序、比较语义与检查范围必须保留。
+
+源端原生强制约束可以免去同一非空条件的数据扫描，但插件必须核验约束确实作用于本次精确来源和列、覆盖已有数据与本次可读数据，而且在主查询期间不会因 DDL、表替换或连接切换失效。仅约束名称相同、目录返回 `nullable=false`、只约束后续写入、一次历史 catalog 观察或 `DECLARED` 结构都不足以证明这些条件。核验与使用之间的 schema 稳定性应由来源实际机制保证，例如同一受保护事务或 statement 的稳定 schema；不能靠先查目录再独立提交查询推断。源端只兑现非空约束时，也不能据此声明可以为优化器兑现所有冻结 PK／UK 等约束。
+
+插件选择同一原子 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 或来源原文放入公开消息。
+
+`CONSTRAINT_VERIFICATION` 与 `CONSISTENT_READ` 是插件对本次保证的责任声明，不是选择某种传输或数据库产品的开关。执行时可真实维持检查与计算的一致性，同时没有可交出的数据版本坐标，此时 `readBasis` 仍应如实为 `Unknown`；它不提供重放保证，也不自动否定已经兑现的单次执行保证。
 
 `execute` 使用 `stageNanos: (String, Long) -> Unit` 回传阶段名称及耗时纳秒；插件直接调用该 Kotlin 函数。取消通过 `WarehouseExecutionControl` 传递，阶段计时不改变资源归属或异常处理责任。
 
@@ -81,6 +93,12 @@ JDBC 实现的 `identityParameters` 为 `jdbcUrl`、可选 `username` 和 `drive
 
 精确 AVG 的原生结果由连接器 `typeSystem.deriveAvgAggType`、`nativeAggregate` 和 `decimalAverageRounding` 如实声明，核心再处理最终业务结果的 DECIMAL 容量和舍入。作者指定最终精度不能补救原生聚合已丢失的信息。原生类型推导明确拒绝时返回 `NATIVE_AGGREGATE_MAPPING_UNAVAILABLE` 和实际输入类型；插件实现者应先研究真实后端映射，不能用浮点、客户端舍入或未经证明的 SUM/COUNT 改写替代。
 
+这三项声明还须覆盖所接受的原生输入类型、实际参与行数及支持的分组／窗口执行形态。原生 AVG 静默算错时，错误值也可能落在合法结果容量内；结果范围、有限值及 `Overflow.FAIL` 检查不构成对后端算术实现的验证。已知错误或尚无保证的映射应继续拒绝，不把最终 DECIMAL、单独的舍入声明或小值样本当作修复。
+
+如果同一输入类型在不同执行形态上返回不同 scale，须区分只增加尾零的表示差异与原生计算已经不同舍入的情况。宽类型只提供容纳空间，不能补回原生结果已经丢失的信息。插件只有在能兑现统一的实际容量及原生舍入时才能声明映射；已证明的原生输入转换或另一原生策略须通过确定的 SQL AST 映射和相同类型推导表达，保留人口、NULL、权重和错误，不在来源执行失败后切换。
+
+当前类型推导与聚合发现只接收技术类型，没有本次输入的业务值域及行数合同。最终输出容量、`Approximate.minimum/maximum` 或一次调查范围不能替代受限输入的证明，也不能据此臆定评分为某个区间。先明确后端实际保证及其适用前提，再判断现有表达能否承载；尚未找到可兑现策略，不等于核心缺少一个范围参数。
+
 作者通过 `describe-script-api` 读取 `read-connector-capabilities` 的方法和正式参数，再在脚本中提交具体聚合查询。例如，以下程序使用已获准来源所指的精确连接器读取 BIGINT 全局 AVG 映射：
 
 ~~~kotlin
@@ -110,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、人口、重复度与数量边界。
@@ -138,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",