[集成 / Integration] 按需评估宿主语言 typed 数据适配 / evaluate typed host-language adapters on demand

中文说明

版本、顺序与当前进度

版本待定 / P2 / deferred。v0.4 #265 提供可移植契约，#264 提供查询绑定；本 issue 仅在具体第二语言调用方准备好后进入。先调查已有 Calcit 需求，面向更广泛采用可评估 TypeScript；进入后只选一个语言与最小传输/生命周期范围，再指定发行版本。

状态与目标

P2、需求触发，不属于 M7 核心路径。

评估 unionid typed value/query API 与 Calcit 等宿主语言之间的最小适配层。unionid 只负责稳定的 ADT/value 表示、参数化查询、结果与错误边界；宿主运行时负责异步调度、缓存、网络、diff、订阅和组件生命周期。

进入条件

仅在真实调用方准备接入且现有 versioned protocol 或 Rust API 无法满足时推进。先记录具体 API 缺口，再决定原生 FFI、进程协议或外部适配 crate；unionid 核心仓库不预设某个框架。

范围与验收

• 用真实调用方列出必须无损映射的 ADT/scalar、错误和资源生命周期。
• 复用现有 typed Value、prepared parameters 与 QueryResponse，不建立第二套查询语义。
• 无法无损表示的值明确报错或使用版本化 wrapper，不静默降精度。
• 适配层有独立测试和容量证据，不改变数据库 writer/transaction 语义。
• 缓存、WebSocket、客户端 diff、Resource/effect 生命周期保持在宿主项目。

数据库订阅、CDC、物化视图和 Calcium/Respo 开发不由本 issue 跟踪。

English Description

Version, sequence, and current progress

Version TBD / P2 / deferred. v0.4 #265 supplies portable contracts and #264 query bindings. Enter this issue only for a ready second-language caller, investigating Calcit first and considering TypeScript for broader adoption. Select one language and minimal transport/lifecycle scope before assigning its release.

Status and goal

P2 and demand-driven; not part of the M7 core path.

Evaluate the smallest adapter between unionid typed value/query APIs and host languages such as Calcit. unionid owns stable ADT/value, parameter, result, and error boundaries. Host runtimes own scheduling, caching, networking, diffs, subscriptions, and component lifecycles.

Entry conditions

Proceed only when a real caller is ready and the versioned protocol or Rust API is insufficient. Record concrete API gaps before choosing native FFI, a process protocol, or an external adapter crate. The core repository does not assume a specific framework.

Scope and acceptance

• Derive required lossless ADT/scalar, error, and resource-lifecycle mappings from a real caller.
• Reuse typed Value, prepared parameters, and QueryResponse without a second query model.
• Reject unsupported lossless mappings or use versioned wrappers; never silently lose precision.
• Keep adapter tests and capacity evidence independent from writer/transaction semantics.
• Keep caches, WebSockets, client diffs, and Resource/effect lifecycles in the host project.

Database subscriptions, CDC, materialized views, and Calcium/Respo development are outside this issue.

Start by reading v0.4 #265 for portable contracts and #264 for query bindings, then identify a real second-language caller and its concrete API gaps. Choose one language and minimal transport or lifecycle scope only after that caller is ready. Done means documented lossless mappings, reuse of typed Value, prepared parameters, and QueryResponse, plus independent adapter tests and capacity evidence without changing writer or transaction semantics.