Merge pull request #33 from A3S-Lab/chore/sync-acl-schema-admission-20260720

docs: sync ACL schema admission

Author: ZhiXiao-Lin

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

@@ -19,6 +19,7 @@ Rust crate 与 Node.js/TypeScript SDK，可以把 ACL 文本解析成 AST，也
 | --- | --- |
 | 语法 | ACL attributes、带 label 的 blocks、nested blocks、lists、objects、strings、numbers、booleans、null、function calls、comments，以及 `=` / `:` assignments。 |
 | Lexer/parser | Bounded parsing 和 multi-diagnostic collection、stable diagnostic codes、UTF-8 byte spans、comment skipping、string escapes、negative numbers 和 scientific notation。 |
+| Admission | Closed-by-default declarative schemas、recursive value rules、stable logical paths、redacted diagnostics，以及 bounded Rust/Node validation reports。 |
 | 函数 | 支持把 `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。 |
@@ -29,10 +30,11 @@ Rust crate 与 Node.js/TypeScript SDK，可以把 ACL 文本解析成 AST，也
 
 - [Syntax](/cn/docs/acl/syntax) 说明 blocks、attributes、values、calls、
   comments 和 parser boundaries。
-- [Rust API](/cn/docs/acl/rust-api) 覆盖 bounded parsing、multi-diagnostic
-  collection、canonical digests、generation、builders 和 AST value helpers。
+- [Rust API](/cn/docs/acl/rust-api) 覆盖 bounded parsing、schema admission、
+  multi-diagnostic collection、canonical digests、generation、builders 和 AST
+  value helpers。
 - [Node SDK](/cn/docs/acl/node-sdk) 覆盖 JavaScript/TypeScript parser、
-  native ACL generator、canonical APIs 和 builders。
+  schema validator、native ACL generator、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、multi-diagnostics、native ACL generation、canonical digests 和 builders。"
+description: "@a3s-lab/acl 的 JavaScript/TypeScript bounded parsing、schema admission、multi-diagnostics、native ACL generation、canonical digests 和 builders。"
 ---
 
 # Node SDK
@@ -47,6 +47,9 @@ const generated = generate(new DocumentBuilder().block(provider).build());
 | `collectDiagnostics(input, limits?)` | 在不构造 partial AST 的前提下收集 bounded diagnostics。 |
 | `DEFAULT_PARSE_LIMITS` | Document bytes、nesting、collection items、token bytes 和 diagnostic count 的 shared immutable defaults。 |
 | `ParseError`、`DIAGNOSTIC_CODES`、`DiagnosticReport` | Stable codes、complete spans、UTF-8 byte offsets、redacted messages 和明确的 truncation state。 |
+| `validateDocument(document, schema, limits?)` | 使用 declarative schema 验证 parsed `Document`，并返回 bounded report。 |
+| `SCHEMA_DIAGNOSTIC_CODES`、`SchemaDiagnostic`、`SchemaReport` | Stable schema codes、logical paths、redacted messages 和明确的 truncation state。 |
+| `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。 |
 | `CanonicalError` | 对 non-finite numbers、non-scalar strings 和 non-portable identifiers 返回不回显值的错误。 |
@@ -99,6 +102,41 @@ Resource-limit diagnostics 仍然是 fatal。Report 最多保存
 `maxDiagnostics` 个 errors，只有在继续观察到超出 budget 的 error 后才会把
 `truncated` 设为 true。
 
+## Schema Admission
+
+使用显式 limits 解析 untrusted text，然后在 activation 前验证得到的
+document：
+
+```typescript
+import {parse, validateDocument, type Schema} from '@a3s-lab/acl';
+
+const limits = {maxDiagnostics: 20};
+const document = parse('version = 1', limits);
+const schema: Schema = {
+  attributes: {
+    version: {required: true, value: {kind: 'Number'}},
+  },
+};
+const report = validateDocument(document, schema, limits);
+```
+
+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。
+
+Schema reports 使用 stable `acl.schema.*` codes 和
+`$.blocks.provider[0].attributes.api_key` 这样的 logical paths。Messages 和
+paths 不包含 attribute values、call arguments 或 block labels。Reports 使用
+`maxDiagnostics`，只有在继续观察到超出 budget 的 schema error 后才会把
+`truncated` 设为 true。
+
+Malformed 或 cyclic programmatic documents、invalid cardinality ranges、empty
+unions、unknown schema fields 和 schema cycles 会在 validation 前以
+`TypeError` 失败。Schema admission 只验证 document shape；numeric ranges、
+secret resolution、provider credentials 和其它 product semantics 仍由 host
+component 负责。
+
 ## Native And Canonical Output
 
 `generate` 只有一个 native ACL output contract。Labels 保留在 block headers；
@@ -110,5 +148,6 @@ semantically unordered attribute 和 object keys 排序。
 
 ## 边界
 
-SDK 是 parser/generator 和 AST builder。它不会加载环境变量、拉取远程配置、验证 provider
-credentials，也不会执行 `env(...)` 等函数。
+SDK 负责解析、生成、构造和验证 declarative ACL document shapes。它不会加载
+环境变量、拉取远程配置、验证 provider credentials，也不会执行 `env(...)`
+等函数。

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

@@ -1,6 +1,6 @@
 ---
 title: Rust API
-description: a3s-acl 的 Rust bounded parsing、multi-diagnostics、canonical digests、native ACL generation、AST 和 builders。
+description: a3s-acl 的 Rust bounded parsing、schema admission、multi-diagnostics、canonical digests、native ACL generation、AST 和 builders。
 ---
 
 # Rust API
@@ -37,6 +37,9 @@ Public crate exports：
 | `parse_with_limits`、`ParseLimits` | 使用显式 document、nesting、collection、token 和 diagnostic limits 解析 untrusted input。 |
 | `collect_diagnostics`、`collect_diagnostics_with_limits` | 在不构造 partial AST 的前提下收集 bounded diagnostics。 |
 | `DiagnosticCode`、`ParseError`、`DiagnosticReport` | 返回 stable codes、UTF-8 byte spans、redacted messages 和明确的 truncation state。 |
+| `validate_document`、`validate_document_with_limits` | 使用 declarative schema 验证 parsed `Document`，并返回 bounded report。 |
+| `Schema`、`AttributeSchema`、`BlockSchema`、`ValueSchema` | 定义 closed-by-default document、block 和 recursive value rules。 |
+| `SchemaDiagnosticCode`、`SchemaDiagnostic`、`SchemaReport` | 返回 stable schema codes、logical paths、redacted messages 和明确的 truncation state。 |
 | `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。 |
@@ -86,6 +89,46 @@ Resource-limit diagnostics 仍然是 fatal。Report 最多保存
 `max_diagnostics` 个 errors，只有在继续观察到超出 budget 的 error 后才会把
 `truncated` 设为 true。
 
+## Schema Admission
+
+使用显式 limits 解析 untrusted text，然后在 activation 前验证得到的
+document：
+
+```rust
+use a3s_acl::{
+    parse_with_limits, validate_document_with_limits, AttributeSchema,
+    ParseLimits, Schema, ValueSchema,
+};
+
+let limits = ParseLimits {
+    max_diagnostics: 20,
+    ..ParseLimits::default()
+};
+let document = parse_with_limits("version = 1", limits)?;
+let schema = Schema::new().attribute(
+    "version",
+    AttributeSchema::required(ValueSchema::number()),
+);
+let report = validate_document_with_limits(&document, &schema, limits);
+assert!(report.is_empty());
+```
+
+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。
+
+Schema reports 使用 stable `acl.schema.*` codes 和
+`$.blocks.provider[0].attributes.api_key` 这样的 logical paths。Messages 和
+paths 不包含 attribute values、call arguments 或 block labels。Report 使用
+`ParseLimits::max_diagnostics`，只有在继续观察到超出 budget 的 schema error
+后才会把 `truncated` 设为 true。
+
+构造 trusted schema 时，invalid cardinality ranges 和 empty unions 会返回
+`SchemaDefinitionError`。Schema admission 只验证 document shape；numeric
+ranges、secret resolution、provider credentials 和其它 product semantics 仍由
+host component 负责。
+
 ## AST
 
 | Type | Fields |

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

@@ -19,6 +19,7 @@ is `@a3s-lab/acl` `0.2.2`. The crate repository metadata points to
 | --- | --- |
 | Syntax | ACL attributes, labeled blocks, nested blocks, lists, objects, strings, numbers, booleans, null, function calls, comments, and `=` / `:` assignments. |
 | Lexer/parser | Bounded parsing and multi-diagnostic collection, stable diagnostic codes, UTF-8 byte spans, comment skipping, string escapes, negative numbers, and scientific notation. |
+| Admission | Closed-by-default declarative schemas, recursive value rules, stable logical paths, redacted diagnostics, and bounded Rust/Node validation reports. |
 | 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. |
@@ -29,10 +30,11 @@ is `@a3s-lab/acl` `0.2.2`. The crate repository metadata points to
 
 - [Syntax](/docs/acl/syntax) documents blocks, attributes, values, calls,
   comments, and parser boundaries.
-- [Rust API](/docs/acl/rust-api) covers bounded parsing, multi-diagnostic
-  collection, canonical digests, generation, builders, and AST value helpers.
+- [Rust API](/docs/acl/rust-api) covers bounded parsing, schema admission,
+  multi-diagnostic collection, canonical digests, generation, builders, and
+  AST value helpers.
 - [Node SDK](/docs/acl/node-sdk) covers the JavaScript/TypeScript parser,
-  native ACL generator, canonical APIs, and builders.
+  schema validator, 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.
 

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

@@ -1,6 +1,6 @@
 ---
 title: Node SDK
-description: JavaScript and TypeScript bounded parsing, multi-diagnostics, native ACL generation, canonical digests, and builders in @a3s-lab/acl.
+description: JavaScript and TypeScript bounded parsing, schema admission, multi-diagnostics, native ACL generation, canonical digests, and builders in @a3s-lab/acl.
 ---
 
 # Node SDK
@@ -47,6 +47,9 @@ const generated = generate(new DocumentBuilder().block(provider).build());
 | `collectDiagnostics(input, limits?)` | Collect bounded diagnostics without constructing a partial AST. |
 | `DEFAULT_PARSE_LIMITS` | Shared immutable defaults for document bytes, nesting, collection items, token bytes, and diagnostic count. |
 | `ParseError`, `DIAGNOSTIC_CODES`, `DiagnosticReport` | Stable codes, complete spans, UTF-8 byte offsets, redacted messages, and explicit truncation state. |
+| `validateDocument(document, schema, limits?)` | Validate a parsed `Document` against a declarative schema with a bounded report. |
+| `SCHEMA_DIAGNOSTIC_CODES`, `SchemaDiagnostic`, `SchemaReport` | Stable schema codes, logical paths, redacted messages, and explicit truncation state. |
+| `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. |
 | `CanonicalError` | Report non-finite numbers, non-scalar strings, and non-portable identifiers without echoing values. |
@@ -99,6 +102,42 @@ Resource-limit diagnostics remain fatal. A report stores at most
 `maxDiagnostics` errors and sets `truncated` only after observing another error
 beyond that budget.
 
+## Schema Admission
+
+Parse untrusted text with explicit limits, then validate the resulting
+document before activating it:
+
+```typescript
+import {parse, validateDocument, type Schema} from '@a3s-lab/acl';
+
+const limits = {maxDiagnostics: 20};
+const document = parse('version = 1', limits);
+const schema: Schema = {
+  attributes: {
+    version: {required: true, value: {kind: 'Number'}},
+  },
+};
+const report = validateDocument(document, schema, limits);
+```
+
+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.
+
+Schema reports use stable `acl.schema.*` codes and logical paths such as
+`$.blocks.provider[0].attributes.api_key`. Messages and paths never include
+attribute values, call arguments, or block labels. Reports use
+`maxDiagnostics` and set `truncated` only after observing an additional schema
+error beyond that budget.
+
+Malformed or cyclic programmatic documents, invalid cardinality ranges, empty
+unions, unknown schema fields, and schema cycles fail with `TypeError` before
+validation. Schema admission validates document shape; host components still
+own numeric ranges, secret resolution, provider credentials, and other product
+semantics.
+
 ## Native And Canonical Output
 
 `generate` has one native ACL output contract. Labels remain in block headers;
@@ -110,6 +149,6 @@ sorting semantically unordered attribute and object keys.
 
 ## Boundary
 
-The SDK is a parser/generator and AST builder. It does not load environment
-variables, fetch remote configuration, validate provider credentials, or execute
-functions such as `env(...)`.
+The SDK parses, generates, builds, and validates declarative ACL document
+shapes. It does not load environment variables, fetch remote configuration,
+validate provider credentials, or execute functions such as `env(...)`.

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

@@ -1,6 +1,6 @@
 ---
 title: Rust API
-description: Rust bounded parsing, multi-diagnostics, canonical digests, native ACL generation, AST, and builders for a3s-acl.
+description: Rust bounded parsing, schema admission, multi-diagnostics, canonical digests, native ACL generation, AST, and builders for a3s-acl.
 ---
 
 # Rust API
@@ -37,6 +37,9 @@ The public crate exports:
 | `parse_with_limits`, `ParseLimits` | Parse untrusted input with explicit document, nesting, collection, token, and diagnostic limits. |
 | `collect_diagnostics`, `collect_diagnostics_with_limits` | Collect bounded diagnostics without constructing a partial AST. |
 | `DiagnosticCode`, `ParseError`, `DiagnosticReport` | Return stable codes, UTF-8 byte spans, redacted messages, and explicit truncation state. |
+| `validate_document`, `validate_document_with_limits` | Validate a parsed `Document` against a declarative schema with a bounded report. |
+| `Schema`, `AttributeSchema`, `BlockSchema`, `ValueSchema` | Define closed-by-default document, block, and recursive value rules. |
+| `SchemaDiagnosticCode`, `SchemaDiagnostic`, `SchemaReport` | Return stable schema codes, logical paths, redacted messages, and explicit truncation state. |
 | `generate` / `generate_acl` | Generate ACL text from a `Document`. |
 | `generate_from_map` | Build ACL text from a `HashMap<String, Value>`. |
 | `canonical_bytes`, `canonical_digest` | Produce stable cross-SDK bytes and an algorithm-prefixed SHA-256 digest. |
@@ -86,6 +89,47 @@ Resource-limit diagnostics remain fatal. A report stores at most
 `max_diagnostics` errors and sets `truncated` only after observing another
 error beyond that budget.
 
+## Schema Admission
+
+Parse untrusted text with explicit limits, then validate the resulting
+document before activating it:
+
+```rust
+use a3s_acl::{
+    parse_with_limits, validate_document_with_limits, AttributeSchema,
+    ParseLimits, Schema, ValueSchema,
+};
+
+let limits = ParseLimits {
+    max_diagnostics: 20,
+    ..ParseLimits::default()
+};
+let document = parse_with_limits("version = 1", limits)?;
+let schema = Schema::new().attribute(
+    "version",
+    AttributeSchema::required(ValueSchema::number()),
+);
+let report = validate_document_with_limits(&document, &schema, limits);
+assert!(report.is_empty());
+```
+
+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.
+
+Schema reports use stable `acl.schema.*` codes and logical paths such as
+`$.blocks.provider[0].attributes.api_key`. Messages and paths never include
+attribute values, call arguments, or block labels. The report uses
+`ParseLimits::max_diagnostics` and sets `truncated` only after observing an
+additional schema error beyond that budget.
+
+Invalid cardinality ranges and empty unions return `SchemaDefinitionError`
+while constructing the trusted schema. Schema admission validates document
+shape; host components still own numeric ranges, secret resolution, provider
+credentials, and other product semantics.
+
 ## AST
 
 | Type | Fields |

compat/cloud-stack.acl

@@ -9,7 +9,7 @@ component "acl" {
   package = "a3s-acl"
   path = "crates/acl"
   repository = "git@github.com:A3S-Lab/ACL.git"
-  revision = "cef613ef945cff9ebbc5a36b983d1daaa1067fdb"
+  revision = "63f3cd73eac4bad84e5bddb0c6c3cc026b19c66e"
   source = "git"
   version = "0.2.2"
 }