docs: sync native ACL generation contract

Author: RoyLin

apps/docs/content/docs/cn/acl/generation-boundaries.mdx

@@ -15,14 +15,29 @@ ACL 适合产品配置，是因为它让配置保持可读、结构化，同时
 | String escaping | Quotes、backslashes、newline、carriage return、tab 会被 escape。 |
 | Lists and objects | Values 会 inline 生成。 |
 | Function calls | Calls 会以语法形式保留，例如 `env("PROVIDER_API_KEY")`。 |
-| Labels | 默认输出把 labels 写在 block headers 中。 |
-| Label-as-attribute mode | Rust 暴露 `GeneratorConfig.labels_as_attrs`；Node 暴露 `generateHCL`。 |
+| Labels | 输出会把所有 labels 写在 native ACL block headers 中。 |
+
+Native ACL 是唯一 output mode。两个 SDK 都不提供 label-as-attribute
+generator mode，并且 Node 会拒绝 generator options，避免静默生成不同
+document shape。
+
+## Canonical Bytes And Digests
+
+当配置需要签名、存储或比较时，Rust 使用 `canonical_bytes` /
+`canonical_digest`，Node 使用 `canonicalBytes` / `canonicalDigest`。
+Canonical output 使用 UTF-8、LF line endings、恰好一个 final newline、
+sorted portable attribute/object keys，并对 duplicate object keys 使用
+last-value-wins。Block、label、list 和 function-argument order 保持有意义。
+
+Finite numbers 使用 ECMAScript shortest-round-trip formatting，negative zero
+输出为 `0`。Unicode scalar sequences 不做 normalization。Digest 格式为
+`sha256:<64 lowercase hexadecimal characters>`。
 
 ## Secret Hygiene
 
 存引用，不存秘密：
 
-```hcl
+```text
 providers "provider" {
   api_key = env("PROVIDER_API_KEY")
   base_url = env("PROVIDER_BASE_URL")

apps/docs/content/docs/cn/acl/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: A3S ACL
-description: A3S 组件使用的类 HCL Agent Configuration Language。
+description: A3S 组件使用的类型化 Agent Configuration Language。
 ---
 
 # A3S ACL
@@ -9,35 +9,36 @@ description: A3S 组件使用的类 HCL Agent Configuration Language。
 Rust crate 与 Node.js/TypeScript SDK，可以把 ACL 文本解析成 AST，也可以从结构化
 值生成 ACL 文本。
 
-当前 Rust crate 是 `a3s-acl` `0.2.1`，当前 Node package 是 `@a3s-lab/acl`
-`0.2.1`。crate repository metadata 指向
+仓库中 Rust crate 是 `a3s-acl` `0.2.2`，Node package 是 `@a3s-lab/acl`
+`0.2.2`。crate repository metadata 指向
 [`A3S-Lab/ACL`](https://github.com/A3S-Lab/ACL)。
 
 ## 能力地图
 
 | 领域 | 当前能力 |
 | --- | --- |
-| 语法 | 类 HCL attributes、带 label 的 blocks、nested blocks、lists、objects、strings、numbers、booleans、null、function calls、comments，以及 `=` / `:` assignments。 |
-| Lexer/parser | Source spans、line/column parse errors、comment skipping、string escapes、negative numbers 和 scientific notation。 |
+| 语法 | ACL attributes、带 label 的 blocks、nested blocks、lists、objects、strings、numbers、booleans、null、function calls、comments，以及 `=` / `:` assignments。 |
+| Lexer/parser | Bounded parsing、stable diagnostic codes、UTF-8 byte spans、comment skipping、string escapes、negative numbers 和 scientific notation。 |
 | 函数 | 支持把 `env(...)`、`concat(...)` 和自定义函数名表示为 first-class call values。 |
 | AST | `Document`、`Block`、typed values、builders、value constructors 和 `Value` accessors。 |
-| 生成 | 支持 parse/generate 双向流程、sorted attributes、string escaping、map generation 和 label-as-attribute output mode。 |
+| 生成 | Native ACL output、block-header labels、sorted attributes 和 objects、type-stable strings，以及 map generation。 |
+| 完整性 | Rust/Node byte-identical canonical UTF-8 和带 algorithm prefix 的 SHA-256 digests。 |
 | SDK | Rust crate `a3s-acl`；Node package `@a3s-lab/acl`，带 TypeScript definitions。 |
 
 ## 从这里开始
 
 - [Syntax](/cn/docs/acl/syntax) 说明 blocks、attributes、values、calls、
   comments 和 parser boundaries。
-- [Rust API](/cn/docs/acl/rust-api) 覆盖 `parse`、`generate`、builders、
-  `GeneratorConfig` 和 AST value helpers。
+- [Rust API](/cn/docs/acl/rust-api) 覆盖 bounded parsing、diagnostics、canonical
+  digests、generation、builders 和 AST value helpers。
 - [Node SDK](/cn/docs/acl/node-sdk) 覆盖 JavaScript/TypeScript parser、
-  generator、builders 和 `generateHCL`。
-- [Generation And Boundaries](/cn/docs/acl/generation-boundaries) 说明 output
-  modes、secret handling，以及 ACL 自身不会评估什么。
+  native ACL generator、canonical APIs 和 builders。
+- [Generation And Boundaries](/cn/docs/acl/generation-boundaries) 说明 stable
+  output、canonical bytes、secret handling 和 host-component ownership。
 
 ## 示例
 
-```hcl
+```text
 default_model = "provider/model-id"
 
 providers "provider" {

apps/docs/content/docs/cn/acl/node-sdk.mdx

@@ -1,6 +1,6 @@
 ---
 title: Node SDK
-description: "@a3s-lab/acl 的 JavaScript/TypeScript parsing、generation、builders、lexer/parser classes 和 HCL output。"
+description: "@a3s-lab/acl 的 JavaScript/TypeScript bounded parsing、native ACL generation、canonical digests 和 builders。"
 ---
 
 # Node SDK
@@ -11,7 +11,7 @@ description: "@a3s-lab/acl 的 JavaScript/TypeScript parsing、generation、buil
 npm install @a3s-lab/acl
 ```
 
-当前仓库中的 package version 是 `0.2.1`。
+仓库中的 package version 是 `0.2.2`。
 
 ## Parse And Generate
 
@@ -43,26 +43,53 @@ const generated = generate(new DocumentBuilder().block(provider).build());
 
 | API | 作用 |
 | --- | --- |
-| `parse(input)` | 把 ACL text 解析成 `Document`。 |
-| `generate(doc)` | 生成 ACL-style text。 |
-| `generateHCL(doc)` | 生成 label-as-attribute HCL-shaped text。 |
+| `parse(input, limits?)` | 使用默认或显式 resource limits，把 ACL text 解析成 `Document`。 |
+| `DEFAULT_PARSE_LIMITS` | Document bytes、nesting、collection items 和 token bytes 的 shared immutable defaults。 |
+| `ParseError`、`DIAGNOSTIC_CODES` | Stable codes、complete spans、UTF-8 byte offsets 和 redacted messages。 |
+| `generate(doc)` | 生成 labels 位于 block headers 的 native ACL text。 |
+| `canonicalBytes(doc)`、`canonicalDigest(doc)` | 生成 stable cross-SDK bytes 和带 algorithm prefix 的 SHA-256 digest。 |
+| `CanonicalError` | 对 non-finite numbers、non-scalar strings 和 non-portable identifiers 返回不回显值的错误。 |
 | `string`、`number`、`boolean`、`bool`、`nullValue`、`list`、`call` | Value constructors。 |
 | `BlockBuilder`、`DocumentBuilder` | Structured document builders。 |
 | `Lexer`、`Parser` | Advanced tokenization/parsing classes。 |
 
 Package 在 `src/index.d.ts` 中提供 TypeScript definitions。
 
-## HCL Output Mode
+## Bounded Admission
 
-Node generator 有 `generateHCL` helper。它会把 labels 写成 generated block 内部的 attributes。
-对 `models` blocks，label attribute 名为 `id`；其它 blocks 使用 `name`。
+在 API boundary 传入显式 limits：
 
 ```typescript
-import {generateHCL} from '@a3s-lab/acl';
-
-const hcl = generateHCL(doc);
+import {ParseError, parse} from '@a3s-lab/acl';
+
+const source = 'limits { max_tasks = 10 }';
+
+try {
+  const document = parse(source, {
+    maxDocumentBytes: 64 * 1024,
+    maxNestingDepth: 32,
+    maxCollectionItems: 1_000,
+    maxTokenBytes: 16 * 1024,
+  });
+} catch (error) {
+  if (error instanceof ParseError) {
+    console.error(error.code, error.span);
+  }
+}
 ```
 
+Document 和 token sizes 使用 UTF-8 bytes。Diagnostic messages 只标识 token
+kinds，不包含 source token values 或 snippets。
+
+## Native And Canonical Output
+
+`generate` 只有一个 native ACL output contract。Labels 保留在 block headers；
+alternate generator modes 和 generator options 均不支持。
+
+签名、durable identity 和 cross-SDK comparisons 应使用 `canonicalBytes` 或
+`canonicalDigest`。Canonical bytes 会保留 ordered ACL constructs，同时对
+semantically unordered attribute 和 object keys 排序。
+
 ## 边界
 
 SDK 是 parser/generator 和 AST builder。它不会加载环境变量、拉取远程配置、验证 provider

apps/docs/content/docs/cn/acl/rust-api.mdx

@@ -1,6 +1,6 @@
 ---
 title: Rust API
-description: a3s-acl 的 Rust parser、generator、AST、builders、value helpers 和 generator configuration。
+description: a3s-acl 的 Rust bounded parsing、diagnostics、canonical digests、native ACL generation、AST 和 builders。
 ---
 
 # Rust API
@@ -9,7 +9,7 @@ description: a3s-acl 的 Rust parser、generator、AST、builders、value helper
 
 ```toml
 [dependencies]
-a3s-acl = "0.2.1"
+a3s-acl = "0.2.2"
 ```
 
 ## Parse And Generate
@@ -34,10 +34,35 @@ Public crate exports：
 | API | 作用 |
 | --- | --- |
 | `parse` / `parse_acl` | 把 ACL text 解析成 `Document`。 |
+| `parse_with_limits`、`ParseLimits` | 使用显式 document、nesting、collection 和 token limits 解析 untrusted input。 |
+| `DiagnosticCode`、`ParseError` | 返回 stable codes、UTF-8 byte spans 和 redacted messages。 |
 | `generate` / `generate_acl` | 从 `Document` 生成 ACL text。 |
 | `generate_from_map` | 从 `HashMap<String, Value>` 生成 ACL text。 |
+| `canonical_bytes`、`canonical_digest` | 生成 stable cross-SDK bytes 和带 algorithm prefix 的 SHA-256 digest。 |
+| `CanonicalError` | 拒绝 unsupported programmatic values 且不回显值。 |
 | `Lexer` / `Parser` | 高级 tokenization 和 parsing entry points。 |
-| `ParseError` | 带 message、line、column 的错误。 |
+
+## Bounded Admission
+
+```rust
+use a3s_acl::{parse_with_limits, ParseLimits};
+
+let input = "limits { max_tasks = 10 }";
+let document = parse_with_limits(
+    input,
+    ParseLimits {
+        max_document_bytes: 64 * 1024,
+        max_nesting_depth: 32,
+        max_collection_items: 1_000,
+        max_token_bytes: 16 * 1024,
+    },
+)?;
+```
+
+Document 和 token sizes 使用 UTF-8 bytes。`ParseError` 提供 stable
+`DiagnosticCode`、带 UTF-8 byte offsets 的 complete source span，以及
+compatibility `line` / `column` fields。Messages 只标识 token kinds，不包含
+source token values 或 snippets。
 
 ## AST
 
@@ -65,20 +90,34 @@ let doc = DocumentBuilder::new().block(provider).build();
 
 Builder helpers 包括 `string`、`number`、`integer`、`boolean`、`null`、`list`、`call`。
 
-## GeneratorConfig
+## Native Generation
 
 ```rust
 use a3s_acl::{Generator, GeneratorConfig};
 
 let generator = Generator::with_config(GeneratorConfig {
-    indent: "  ",
+    indent: "    ",
     comments: false,
-    labels_as_attrs: true,
 });
+let text = generator.generate(&doc);
+```
+
+Generation 只有一个 native ACL contract：block labels 保留在 block headers。
+不存在 label-as-attribute compatibility mode。
+
+## Canonical Bytes And Digests
+
+```rust
+use a3s_acl::{canonical_bytes, canonical_digest};
+
+let bytes = canonical_bytes(&doc)?;
+let digest = canonical_digest(&doc)?;
+assert!(digest.starts_with("sha256:"));
 ```
 
-`labels_as_attrs` 会把 block labels 写成 block 内部 attributes，而不是写在 block header 中。
-当 integration 更偏向 attribute-oriented HCL shape 时可以使用。
+签名、durable identity 和 cross-SDK comparisons 应使用 canonical APIs。
+Canonical bytes 会保留 ordered ACL constructs，同时对 semantically
+unordered attribute 和 object keys 排序。
 
 ## Notes
 

apps/docs/content/docs/cn/acl/syntax.mdx

@@ -5,12 +5,13 @@ description: A3S ACL 的 blocks、labels、attributes、values、calls、comment
 
 # ACL Syntax
 
-ACL 刻意接近 HCL：document 会被解析成一组 named blocks。Top-level bare attributes 会表示成
-single-attribute blocks，因此编辑工具可以使用统一 AST 形态。
+ACL 使用紧凑的 attribute-and-block syntax。Document 会被解析成一组 named
+blocks。Top-level bare attributes 会表示成 single-attribute blocks，因此编辑
+工具可以使用统一 AST 形态。
 
 ## Blocks And Attributes
 
-```hcl
+```text
 default_model = "provider/model-id"
 
 providers "provider" {
@@ -51,10 +52,21 @@ Lexer 里有 `+=` token，但 parser 当前接受的是 `=` 和 `:` attributes
 Double-quoted strings 支持 newline、carriage return、tab、backslash、escaped quote 等常见 escapes。
 Single-quoted strings 也会被 tokenized。
 
-## Parse Errors
+## Resource Limits And Parse Errors
 
-`ParseError` 包含 message、line 和 column。Lexer 为 tokens 跟踪 spans，方便 editor integrations
-定位失败位置。
+两个 SDK 的 high-level parser 使用相同 defaults：
+
+| Limit | Default |
+| --- | ---: |
+| UTF-8 document size | 1 MiB |
+| Structural nesting depth | 64 |
+| Items in one document or collection | 10,000 |
+| UTF-8 source token size | 256 KiB |
+
+`ParseError` 提供 stable machine-readable code、complete source span 和
+compatibility line/column fields。Span offsets 使用 UTF-8 bytes，因此即使
+error 前有 Unicode，Rust 和 Node 也会定位到相同位置。Messages 只标识 token
+kinds，不回显 token values 或 source snippets。
 
 ## Evaluation Boundary
 

apps/docs/content/docs/en/acl/generation-boundaries.mdx

@@ -16,14 +16,29 @@ and structured while leaving sensitive value resolution to the host component.
 | String escaping | Quotes, backslashes, newline, carriage return, and tab are escaped. |
 | Lists and objects | Values are generated inline. |
 | Function calls | Calls are preserved as syntax, for example `env("PROVIDER_API_KEY")`. |
-| Labels | Default output writes labels in block headers. |
-| Label-as-attribute mode | Rust exposes `GeneratorConfig.labels_as_attrs`; Node exposes `generateHCL`. |
+| Labels | Output writes every label in its native ACL block header. |
+
+Native ACL is the only output mode. Neither SDK provides a label-as-attribute
+generator mode, and Node rejects generator options instead of silently
+producing a different document shape.
+
+## Canonical Bytes And Digests
+
+Use `canonical_bytes` / `canonical_digest` in Rust and `canonicalBytes` /
+`canonicalDigest` in Node when configuration is signed, stored, or compared.
+Canonical output uses UTF-8, LF line endings, exactly one final newline, sorted
+portable attribute and object keys, and last-value-wins duplicate object keys.
+Block, label, list, and function-argument order remains significant.
+
+Finite numbers use ECMAScript shortest-round-trip formatting, including `0` for
+negative zero. Unicode scalar sequences are preserved without normalization.
+The digest format is `sha256:<64 lowercase hexadecimal characters>`.
 
 ## Secret Hygiene
 
 Store references, not secrets:
 
-```hcl
+```text
 providers "provider" {
   api_key = env("PROVIDER_API_KEY")
   base_url = env("PROVIDER_BASE_URL")

apps/docs/content/docs/en/acl/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: A3S ACL
-description: HCL-like Agent Configuration Language used across A3S components.
+description: Typed Agent Configuration Language used across A3S components.
 ---
 
 # A3S ACL
@@ -9,35 +9,36 @@ description: HCL-like Agent Configuration Language used across A3S components.
 configuration. It provides a Rust crate and a Node.js/TypeScript SDK for parsing
 ACL text into an AST and generating ACL text back from structured values.
 
-The current Rust crate is `a3s-acl` `0.2.1`, and the current Node package is
-`@a3s-lab/acl` `0.2.1`. The crate repository metadata points to
+The checked-in Rust crate is `a3s-acl` `0.2.2`, and the checked-in Node package
+is `@a3s-lab/acl` `0.2.2`. The crate repository metadata points to
 [`A3S-Lab/ACL`](https://github.com/A3S-Lab/ACL).
 
 ## Capability Map
 
 | Area | Current capability |
 | --- | --- |
-| Syntax | HCL-like attributes, labeled blocks, nested blocks, lists, objects, strings, numbers, booleans, null, function calls, comments, and `=` / `:` assignments. |
-| Lexer/parser | Source spans, line/column parse errors, comment skipping, string escapes, negative numbers, and scientific notation. |
+| Syntax | ACL attributes, labeled blocks, nested blocks, lists, objects, strings, numbers, booleans, null, function calls, comments, and `=` / `:` assignments. |
+| Lexer/parser | Bounded parsing, stable diagnostic codes, UTF-8 byte spans, comment skipping, string escapes, negative numbers, and scientific notation. |
 | Functions | First-class call values such as `env(...)`, `concat(...)`, and custom function names. |
 | AST | `Document`, `Block`, typed values, builders, value constructors, and `Value` accessors. |
-| Generation | Bidirectional parse/generate flow, sorted attributes, string escaping, map generation, and label-as-attribute output mode. |
+| Generation | Native ACL output, block-header labels, sorted attributes and objects, type-stable strings, and map generation. |
+| Integrity | Byte-identical Rust/Node canonical UTF-8 and algorithm-prefixed SHA-256 digests. |
 | SDKs | Rust crate `a3s-acl`; Node package `@a3s-lab/acl` with TypeScript definitions. |
 
 ## Start Here
 
 - [Syntax](/docs/acl/syntax) documents blocks, attributes, values, calls,
   comments, and parser boundaries.
-- [Rust API](/docs/acl/rust-api) covers `parse`, `generate`, builders,
-  `GeneratorConfig`, and AST value helpers.
+- [Rust API](/docs/acl/rust-api) covers bounded parsing, diagnostics, canonical
+  digests, generation, builders, and AST value helpers.
 - [Node SDK](/docs/acl/node-sdk) covers the JavaScript/TypeScript parser,
-  generator, builders, and `generateHCL`.
-- [Generation And Boundaries](/docs/acl/generation-boundaries) explains output
-  modes, secret handling, and what ACL does not evaluate by itself.
+  native ACL generator, canonical APIs, and builders.
+- [Generation And Boundaries](/docs/acl/generation-boundaries) explains stable
+  output, canonical bytes, secret handling, and host-component ownership.
 
 ## Example
 
-```hcl
+```text
 default_model = "provider/model-id"
 
 providers "provider" {