Merge pull request #34 from A3S-Lab/chore/sync-acl-unordered-blocks-20260720

docs: sync ACL unordered block normalization

Author: ZhiXiao-Lin

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

@@ -27,7 +27,17 @@ document shape。
 `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 保持有意义。
+last-value-wins。这些 base APIs 会保留 block、label、list 和
+function-argument order。
+
+完成 schema admission 后，Rust 的
+`canonical_bytes_with_schema` / `canonical_digest_with_schema` 和 Node 的
+`canonicalBytesWithSchema` / `canonicalDigestWithSchema` 可以递归规范化 schema
+rule 标记为 `unordered` 的同一种 declared block name 的 occurrences。
+Matching blocks 按 canonical UTF-8 bytes 比较，并且只替换原有 slots。其它
+names、unknown blocks、labels、lists、calls 和 unmarked blocks 仍然保持顺序。
+Schema-aware APIs 只把 schema 用作 normalization metadata，不会执行
+admission。
 
 Finite numbers 使用 ECMAScript shortest-round-trip formatting，negative zero
 输出为 `0`。Unicode scalar sequences 不做 normalization。Digest 格式为
@@ -55,11 +65,14 @@ ACL 负责：
 - 从 AST 生成 text
 - value constructors 和 document builders
 - parser diagnostics
+- declarative document-shape schemas 和 bounded validation reports
+- base 和 schema-aware canonical bytes 与 digests
 - language-neutral config shape
 
 宿主组件负责：
 
-- 验证 block 或 attribute 是否允许
+- 定义每个 product boundary 使用的 trusted schema
+- 验证 document shape 之外的 domain rules
 - 执行 function calls
 - 解析 environment variables 或 secret-store references
 - 应用 defaults

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

@@ -23,18 +23,19 @@ Rust crate 与 Node.js/TypeScript SDK，可以把 ACL 文本解析成 AST，也
 | 函数 | 支持把 `env(...)`、`concat(...)` 和自定义函数名表示为 first-class call values。 |
 | AST | `Document`、`Block`、typed values、builders、value constructors 和 `Value` accessors。 |
 | 生成 | 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。 |
+| 完整性 | Rust/Node byte-identical canonical UTF-8、带 algorithm prefix 的 SHA-256 digests，以及对 declared unordered block occurrences 的 recursive schema-aware normalization。 |
 | 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) 覆盖 bounded parsing、schema admission、
-  multi-diagnostic collection、canonical digests、generation、builders 和 AST
-  value helpers。
+  multi-diagnostic collection、schema-aware canonical digests、generation、
+  builders 和 AST value helpers。
 - [Node SDK](/cn/docs/acl/node-sdk) 覆盖 JavaScript/TypeScript parser、
-  schema validator、native ACL generator、canonical APIs 和 builders。
+  schema validator、native ACL generator、schema-aware canonical APIs 和
+  builders。
 - [Generation And Boundaries](/cn/docs/acl/generation-boundaries) 说明 stable
   output、canonical bytes、secret handling 和 host-component ownership。
 

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

@@ -1,6 +1,6 @@
 ---
 title: Node SDK
-description: "@a3s-lab/acl 的 JavaScript/TypeScript bounded parsing、schema admission、multi-diagnostics、native ACL generation、canonical digests 和 builders。"
+description: "@a3s-lab/acl 的 JavaScript/TypeScript bounded parsing、schema admission、multi-diagnostics、native generation、schema-aware canonical digests 和 builders。"
 ---
 
 # Node SDK
@@ -52,6 +52,7 @@ const generated = generate(new DocumentBuilder().block(provider).build());
 | `Schema`、`AttributeSchema`、`BlockSchema`、`ValueSchema` | Closed-by-default document、block 和 recursive value rules 的 TypeScript definitions。 |
 | `generate(doc)` | 生成 labels 位于 block headers 的 native ACL text。 |
 | `canonicalBytes(doc)`、`canonicalDigest(doc)` | 生成 stable cross-SDK bytes 和带 algorithm prefix 的 SHA-256 digest。 |
+| `canonicalBytesWithSchema(doc, schema)`、`canonicalDigestWithSchema(doc, schema)` | 生成 bytes 或 digest 前，递归规范化 schema-declared unordered block occurrences。 |
 | `CanonicalError` | 对 non-finite numbers、non-scalar strings 和 non-portable identifiers 返回不回显值的错误。 |
 | `string`、`number`、`boolean`、`bool`、`nullValue`、`list`、`call` | Value constructors。 |
 | `BlockBuilder`、`DocumentBuilder` | Structured document builders。 |
@@ -124,6 +125,8 @@ Schemas 默认拒绝 undeclared attributes、blocks 和 object fields。它们
 required/optional attributes、block occurrence 和 label cardinalities，以及
 recursive `Any`、`String`、`Number`、`Bool`、`Null`、`List`、`Object`、
 `Call` 和 `OneOf` rules。Extension points 必须使用相应的显式 allow flag。
+Block rule 的 `unordered: true` metadata 只影响 schema-aware
+canonicalization，不改变 validation。
 
 Schema reports 使用 stable `acl.schema.*` codes 和
 `$.blocks.provider[0].attributes.api_key` 这样的 logical paths。Messages 和
@@ -146,6 +149,44 @@ alternate generator modes 和 generator options 均不支持。
 `canonicalDigest`。Canonical bytes 会保留 ordered ACL constructs，同时对
 semantically unordered attribute 和 object keys 排序。
 
+完成 schema admission 后，如果 trusted schema 把 repeatable block
+occurrences 声明为 unordered，则使用 schema-aware APIs：
+
+```typescript
+import {
+  canonicalBytes,
+  canonicalBytesWithSchema,
+  canonicalDigestWithSchema,
+  parse,
+  validateDocument,
+  type Schema,
+} from '@a3s-lab/acl';
+
+const document = parse('provider "z" {}\nprovider "a" {}');
+const schema: Schema = {
+  blocks: {
+    provider: {
+      labels: {min: 1, max: 1},
+      unordered: true,
+    },
+  },
+};
+const report = validateDocument(document, schema);
+if (report.diagnostics.length > 0 || report.truncated) {
+  throw new Error('document failed schema admission');
+}
+
+const orderedBytes = canonicalBytes(document);
+const normalizedBytes = canonicalBytesWithSchema(document, schema);
+const digest = canonicalDigestWithSchema(document, schema);
+```
+
+对于每个 body，normalization 会递归按照 canonical UTF-8 bytes 对每一种相同
+declared block name 的 occurrences 排序，同时保留它们原有的 positions。
+其它 block types、unknown blocks、labels、lists、calls 和 unmarked blocks
+仍然保持顺序。Schema-aware APIs 只把 schema 用作 normalization metadata，
+不会自行执行 admission。
+
 ## 边界
 
 SDK 负责解析、生成、构造和验证 declarative ACL document shapes。它不会加载

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

@@ -1,6 +1,6 @@
 ---
 title: Rust API
-description: a3s-acl 的 Rust bounded parsing、schema admission、multi-diagnostics、canonical digests、native ACL generation、AST 和 builders。
+description: a3s-acl 的 Rust bounded parsing、schema admission、multi-diagnostics、schema-aware canonical digests、native ACL generation、AST 和 builders。
 ---
 
 # Rust API
@@ -43,6 +43,7 @@ Public crate exports：
 | `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。 |
+| `canonical_bytes_with_schema`、`canonical_digest_with_schema` | 生成 bytes 或 digest 前，递归规范化 schema-declared unordered block occurrences。 |
 | `CanonicalError` | 拒绝 unsupported programmatic values 且不回显值。 |
 | `Lexer` / `Parser` | 高级 tokenization 和 parsing entry points。 |
 
@@ -117,6 +118,8 @@ Schemas 默认拒绝 undeclared attributes、blocks 和 object fields。它们
 required/optional attributes、block occurrence 和 label cardinalities，以及
 recursive `Any`、`String`、`Number`、`Bool`、`Null`、`List`、`Object`、
 `Call` 和 `OneOf` rules。Extension points 必须使用相应的显式 allow flag。
+`BlockSchema::unordered(true)` 会把 matching occurrences 标记为 schema-aware
+canonicalization 中的 semantically unordered；它不会改变 validation。
 
 Schema reports 使用 stable `acl.schema.*` codes 和
 `$.blocks.provider[0].attributes.api_key` 这样的 logical paths。Messages 和
@@ -173,16 +176,39 @@ Generation 只有一个 native ACL contract：block labels 保留在 block heade
 ## Canonical Bytes And Digests
 
 ```rust
-use a3s_acl::{canonical_bytes, canonical_digest};
+use a3s_acl::{
+    canonical_bytes, canonical_bytes_with_schema, canonical_digest_with_schema,
+    parse, validate_document, BlockSchema, Cardinality, Schema,
+};
+
+let document = parse(
+    "provider \"z\" {}\nprovider \"a\" {}",
+)?;
+let schema = Schema::new().block(
+    "provider",
+    BlockSchema::new(Schema::new())
+        .labels(Cardinality::exactly(1))
+        .unordered(true),
+);
+assert!(validate_document(&document, &schema).is_empty());
 
-let bytes = canonical_bytes(&doc)?;
-let digest = canonical_digest(&doc)?;
+let ordered_bytes = canonical_bytes(&document)?;
+let normalized_bytes = canonical_bytes_with_schema(&document, &schema)?;
+let digest = canonical_digest_with_schema(&document, &schema)?;
+assert_ne!(ordered_bytes, normalized_bytes);
 assert!(digest.starts_with("sha256:"));
 ```
 
 签名、durable identity 和 cross-SDK comparisons 应使用 canonical APIs。
 Canonical bytes 会保留 ordered ACL constructs，同时对 semantically
-unordered attribute 和 object keys 排序。
+unordered attribute 和 object keys 排序。完成 schema admission 后，
+schema-aware APIs 还会对 rule 设置了 `unordered` 的每一种 declared block
+name 的 occurrences 排序。Normalization 会递归执行并比较 canonical UTF-8
+bytes，但保留 occurrences 的原有 positions，因此其它 block types 和 unknown
+blocks 不会移动。Labels、lists、calls 和 unmarked blocks 仍然保持顺序。
+
+Schema-aware canonicalization 不会执行 schema admission。把 trusted schema
+用作 normalization metadata 前，需要单独验证 document。
 
 ## Notes
 

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

@@ -28,7 +28,16 @@ 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.
+These base APIs preserve block, label, list, and function-argument order.
+
+After schema admission, Rust
+`canonical_bytes_with_schema` / `canonical_digest_with_schema` and Node
+`canonicalBytesWithSchema` / `canonicalDigestWithSchema` can recursively
+normalize occurrences of a declared block name whose schema rule marks it
+`unordered`. Matching blocks are compared by canonical UTF-8 bytes and replace
+only their original slots. Other names, unknown blocks, labels, lists, calls,
+and unmarked blocks remain ordered. The schema-aware APIs use the schema only
+as normalization metadata; they do not perform admission.
 
 Finite numbers use ECMAScript shortest-round-trip formatting, including `0` for
 negative zero. Unicode scalar sequences are preserved without normalization.
@@ -58,11 +67,14 @@ ACL owns:
 - generating text from AST
 - value constructors and document builders
 - parser diagnostics
+- declarative document-shape schemas and bounded validation reports
+- base and schema-aware canonical bytes and digests
 - language-neutral config shape
 
 The host component owns:
 
-- validating whether a block or attribute is allowed
+- defining the trusted schema at each product boundary
+- validating domain rules beyond document shape
 - evaluating function calls
 - resolving environment variables or secret-store references
 - applying defaults

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

@@ -23,18 +23,19 @@ is `@a3s-lab/acl` `0.2.2`. The crate repository metadata points to
 | 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 | 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. |
+| Integrity | Byte-identical Rust/Node canonical UTF-8, algorithm-prefixed SHA-256 digests, and recursive schema-aware normalization for declared unordered block occurrences. |
 | 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 bounded parsing, schema admission,
-  multi-diagnostic collection, canonical digests, generation, builders, and
-  AST value helpers.
+  multi-diagnostic collection, schema-aware canonical digests, generation,
+  builders, and AST value helpers.
 - [Node SDK](/docs/acl/node-sdk) covers the JavaScript/TypeScript parser,
-  schema validator, native ACL generator, canonical APIs, and builders.
+  schema validator, native ACL generator, schema-aware canonical APIs, and
+  builders.
 - [Generation And Boundaries](/docs/acl/generation-boundaries) explains stable
   output, canonical bytes, secret handling, and host-component ownership.
 

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

@@ -1,6 +1,6 @@
 ---
 title: Node SDK
-description: JavaScript and TypeScript bounded parsing, schema admission, multi-diagnostics, native ACL generation, canonical digests, and builders in @a3s-lab/acl.
+description: JavaScript and TypeScript bounded parsing, schema admission, multi-diagnostics, native generation, schema-aware canonical digests, and builders in @a3s-lab/acl.
 ---
 
 # Node SDK
@@ -52,6 +52,7 @@ const generated = generate(new DocumentBuilder().block(provider).build());
 | `Schema`, `AttributeSchema`, `BlockSchema`, `ValueSchema` | TypeScript definitions for closed-by-default document, block, and recursive value rules. |
 | `generate(doc)` | Generate native ACL text with labels in block headers. |
 | `canonicalBytes(doc)`, `canonicalDigest(doc)` | Produce stable cross-SDK bytes and an algorithm-prefixed SHA-256 digest. |
+| `canonicalBytesWithSchema(doc, schema)`, `canonicalDigestWithSchema(doc, schema)` | Recursively normalize schema-declared unordered block occurrences before producing bytes or a digest. |
 | `CanonicalError` | Report non-finite numbers, non-scalar strings, and non-portable identifiers without echoing values. |
 | `string`, `number`, `boolean`, `bool`, `nullValue`, `list`, `call` | Value constructors. |
 | `BlockBuilder`, `DocumentBuilder` | Structured document builders. |
@@ -124,7 +125,8 @@ Schemas reject undeclared attributes, blocks, and object fields by default.
 They can declare required or optional attributes, block occurrence and label
 cardinalities, and recursive `Any`, `String`, `Number`, `Bool`, `Null`, `List`,
 `Object`, `Call`, and `OneOf` rules. Extension points require the corresponding
-explicit allow flag.
+explicit allow flag. A block rule's `unordered: true` metadata affects only
+schema-aware canonicalization, not validation.
 
 Schema reports use stable `acl.schema.*` codes and logical paths such as
 `$.blocks.provider[0].attributes.api_key`. Messages and paths never include
@@ -147,6 +149,44 @@ Use `canonicalBytes` or `canonicalDigest` for signatures, durable identity, and
 cross-SDK comparisons. Canonical bytes preserve ordered ACL constructs while
 sorting semantically unordered attribute and object keys.
 
+After schema admission, use the schema-aware APIs when a trusted schema
+declares repeatable block occurrences as unordered:
+
+```typescript
+import {
+  canonicalBytes,
+  canonicalBytesWithSchema,
+  canonicalDigestWithSchema,
+  parse,
+  validateDocument,
+  type Schema,
+} from '@a3s-lab/acl';
+
+const document = parse('provider "z" {}\nprovider "a" {}');
+const schema: Schema = {
+  blocks: {
+    provider: {
+      labels: {min: 1, max: 1},
+      unordered: true,
+    },
+  },
+};
+const report = validateDocument(document, schema);
+if (report.diagnostics.length > 0 || report.truncated) {
+  throw new Error('document failed schema admission');
+}
+
+const orderedBytes = canonicalBytes(document);
+const normalizedBytes = canonicalBytesWithSchema(document, schema);
+const digest = canonicalDigestWithSchema(document, schema);
+```
+
+For each body, normalization recursively sorts occurrences of each same
+declared block name by canonical UTF-8 bytes while retaining their existing
+positions. Other block types, unknown blocks, labels, lists, calls, and
+unmarked blocks remain ordered. The schema-aware APIs use the schema only as
+normalization metadata and do not perform admission themselves.
+
 ## Boundary
 
 The SDK parses, generates, builds, and validates declarative ACL document