feat: implement advanced state API for Go and Python (#214)

- Go SDK: add state package with codec, keyed state, and structures
  - codec: bool/bytes/float/int/string/uint/json and ordered types
- keyed: Value, List, Map, Aggregating, Reducing, PriorityQueue keyed
states
  - structures: underlying implementations for each state type
- Python API: refactor store into codec, keyed, structures submodules
  - keyed: KeyedValueState, KeyedListState, KeyedMapState, etc.
  - structures: state structures aligned with Go
- Runtime: update fs_context to work with new state API

Made-with: Cursor

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Adds new Go and Python “advanced state” libraries and updates the Go
runtime context concurrency behavior, which could affect state access
and build/runtime integration. Main risk is correctness/performance of
the new state encodings (ordered codecs, merge/list packing) and any
assumptions about thread-safety after removing locking.
> 
> **Overview**
> Introduces a new **Go advanced SDK** (`go-sdk-advanced`) providing
typed state abstractions (`ValueState`, `ListState`, `MapState`,
`PriorityQueueState`, `AggregatingState`, `ReducingState`) plus keyed
variants via factories, all backed by the existing low-level `Store` and
a new codec layer with ordered primitive codecs and `DefaultCodecFor`.
> 
> Adds a new **Python advanced state package**
(`functionstream-api-advanced`) with parallel codec/state/keyed APIs and
packaging metadata, and wires builds/docs to recognize the new advanced
modules (Makefile `PYTHONPATH` update, `.gitignore` build output,
README/doc links, and new advanced-state API guides in EN/ZH).
> 
> Also tweaks the Go SDK runtime context implementation by removing
internal mutex guarding `closed`/`stores`, changing thread-safety
expectations for `Emit`/`GetOrCreateStore`/`Close`.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
e93c4a4. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: luoluoyuyu

.gitignore

@@ -22,6 +22,8 @@ examples/python-processor/build/**
 examples/python-processor/dependencies/**
 python/functionstream-client/src/fs_client/_proto/
 python/functionstream-api/build
+python/functionstream-api-advanced/build
+
 
 
 # python Runtime - Build artifacts and intermediate files

Makefile

@@ -82,7 +82,7 @@ build-lite: .check-env
 .build-wasm:
 	$(call log,WASM,Building Python Runtime using $(PYTHON_EXEC))
 	@cd $(PYTHON_ROOT)/functionstream-runtime && \
-		PYTHONPATH=../functionstream-api ../../$(PYTHON_EXEC) build.py > /dev/null
+		PYTHONPATH=../functionstream-api:../functionstream-api-advanced ../../$(PYTHON_EXEC) build.py > /dev/null
 	@[ -f "$(WASM_SOURCE)" ] || (printf "$(C_R)[X] WASM Build Failed$(C_0)\n" && exit 1)
 
 dist: build

README-zh.md

@@ -206,7 +206,8 @@ function-stream-<version>/
 | [Function 任务配置规范](docs/function-configuration-zh.md) | 任务定义规范        |
 | [SQL CLI 交互式管理指南](docs/sql-cli-guide-zh.md)          | 交互式管理指南       |
 | [Function 管理与开发指南](docs/function-development-zh.md)  | 管理与开发指南       |
-| [Python SDK 开发与交互指南](docs/python-sdk-guide-zh.md)    | Python SDK 指南 |
+| [Go SDK 开发与交互指南](docs/Go-SDK/go-sdk-guide-zh.md)     | Go SDK 指南        |
+| [Python SDK 开发与交互指南](docs/Python-SDK/python-sdk-guide-zh.md) | Python SDK 指南 |
 
 ## 配置
 

README.md

@@ -205,7 +205,8 @@ We provide a robust shell script to manage the server process, capable of handli
 | [Function Configuration](docs/function-configuration.md) | Task Definition Specification     |
 | [SQL CLI Guide](docs/sql-cli-guide.md)                   | Interactive Management Guide      |
 | [Function Development](docs/function-development.md)     | Management & Development Guide    |
-| [Python SDK Guide](docs/python-sdk-guide.md)             | Python SDK Guide                  |
+| [Go SDK Guide](docs/Go-SDK/go-sdk-guide.md)              | Go SDK Guide                      |
+| [Python SDK Guide](docs/Python-SDK/python-sdk-guide.md)   | Python SDK Guide                  |
 
 ## Configuration
 

docs/Go-SDK/go-sdk-advanced-state-api-zh.md

@@ -263,7 +263,7 @@ create function with (
 );
 ```
 
-config.yaml 中需配置 `name`、`type: processor`、`input-groups`、`outputs`（如 Kafka）。详见 [Function 配置](function-configuration-zh.md) 与 [examples/go-processor/README.md](../examples/go-processor/README.md)。
+config.yaml 中需配置 `name`、`type: processor`、`input-groups`、`outputs`（如 Kafka）。详见 [Function 配置](../function-configuration-zh.md) 与 [examples/go-processor/README.md](../../examples/go-processor/README.md)。
 
 ---
 
@@ -301,7 +301,18 @@ if err != nil {
 
 ---
 
-## 七、目录结构参考
+## 七、高级状态 API（进阶文档）
+
+本指南仅覆盖**低阶 go-sdk**（Driver、Context、Store、目录结构）。**高级状态 API**（Codec、ValueState、ListState、MapState、PriorityQueueState、AggregatingState、ReducingState、Keyed\* 工厂与用法）由独立库 **go-sdk-advanced** 提供，完整说明、Codec 约定、构造函数表与示例均在进阶文档中：
+
+- **[Go SDK — 高级状态 API](go-sdk-advanced-state-api-zh.md)**（中文）
+- [Go SDK — Advanced State API](go-sdk-advanced-state-api.md)（英文）
+
+---
+
+## 八、目录结构参考
+
+**低阶库 go-sdk**：
 
 ```text
 go-sdk/
@@ -317,8 +328,20 @@ go-sdk/
 │   ├── runtime.go
 │   ├── context.go
 │   └── store.go
+├── state/
+│   └── common/       # 公共辅助（Store 类型别名、DupBytes）
 ├── wit/              # processor.wit 及依赖（可由 make wit 生成）
 └── bindings/         # wit-bindgen-go 生成的 Go 代码（make bindings）
 ```
 
-更多示例与 SQL 操作见 [examples/go-processor/README.md](../examples/go-processor/README.md)、[SQL CLI 指南](sql-cli-guide-zh.md)。
+**高阶库 go-sdk-advanced**（依赖 go-sdk，含 Codec 与全部状态类型）：
+
+```text
+go-sdk-advanced/
+├── go.mod            # require go-sdk
+├── codec/            # Codec[T]、DefaultCodecFor、内置与 JSON codec
+├── structures/       # ValueState、ListState、MapState、PriorityQueue、Aggregating、Reducing
+└── keyed/            # Keyed 状态工厂（value、list、map、PQ、aggregating、reducing）
+```
+
+更多示例与 SQL 操作见 [examples/go-processor/README.md](../../examples/go-processor/README.md)、[SQL CLI 指南](../sql-cli-guide-zh.md)。

docs/Go-SDK/go-sdk-advanced-state-api.md

@@ -263,7 +263,7 @@ create function with (
 );
 ```
 
-Configure `name`, `type: processor`, `input-groups`, and `outputs` (e.g. Kafka) in config.yaml. See [Function Configuration](function-configuration.md) and [examples/go-processor/README.md](../examples/go-processor/README.md).
+Configure `name`, `type: processor`, `input-groups`, and `outputs` (e.g. Kafka) in config.yaml. See [Function Configuration](../function-configuration.md) and [examples/go-processor/README.md](../../examples/go-processor/README.md).
 
 ---
 
@@ -301,7 +301,18 @@ if err != nil {
 
 ---
 
-## 7. Directory Layout
+## 7. Advanced State API (see advanced doc)
+
+This guide covers only the **low-level go-sdk** (Driver, Context, Store, directory layout). The **advanced state API** (Codec, ValueState, ListState, MapState, PriorityQueueState, AggregatingState, ReducingState, Keyed\* factories and usage) is provided by a separate library **go-sdk-advanced**. Full reference, codec contract, constructor tables, and examples are in the advanced document:
+
+- **[Go SDK — Advanced State API](go-sdk-advanced-state-api.md)** (English)
+- [Go SDK — 高级状态 API](go-sdk-advanced-state-api-zh.md) (中文)
+
+---
+
+## 8. Directory Layout
+
+**Low-level library (go-sdk):**
 
 ```text
 go-sdk/
@@ -317,8 +328,10 @@ go-sdk/
 │   ├── runtime.go
 │   ├── context.go
 │   └── store.go
+├── state/
+│   └── common/       # Shared helpers (Store type alias, DupBytes)
 ├── wit/              # processor.wit and deps (make wit)
 └── bindings/         # Generated by wit-bindgen-go (make bindings)
 ```
 
-For more examples and SQL operations, see [examples/go-processor/README.md](../examples/go-processor/README.md) and the [SQL CLI Guide](sql-cli-guide.md).
+For more examples and SQL operations, see [examples/go-processor/README.md](../../examples/go-processor/README.md) and the [SQL CLI Guide](../sql-cli-guide.md).