`assertions:` 块
Component、Feature、Recipe 和 FeatureRecipe 带有一个可选的 spec.assertions: 字段——一个由具名规则组成的映射,编译器在 schema 校验之后、渲染之前对其求值。每个键是一个规则标识符,会出现在失败消息中;每个值是一个 Go 模板主体。直接写在 assertions: 下的单个模板主体不符合该字段的结构,会在读取实体时被拒绝,因此每条规则都要在各自的名称下编写。该块用于表达 JSON Schema 无法简洁描述的跨字段规则:涉及多个字段、且没有哪一个字段是“被校验的那个”的不变量。本页介绍编写语法、求值阶段、模板上下文,以及 Component / Feature 断言(契约的架构不变量)与 Recipe / FeatureRecipe 断言(特定 provider 的实现不变量)之间的职责划分。
对于单字段约束(范围、模式、枚举、格式),请在 schema: 中使用 JSON Schema 的原生关键字。对于单字段的自定义谓词,请使用紧凑形式的 validate: 字段。对于条件结构,请使用 when:。assertions: 字段是对这些机制的补充——它是真正的跨字段规则的归属之处。
该字段出现的位置
可以携带 assertions: 的四种实体:
- Component —— Component 契约的架构不变量。
- Feature —— Feature 契约的架构不变量。
- Recipe —— 该 Recipe 底层 chart 或模块的实现不变量。
- FeatureRecipe —— 该 FeatureRecipe 底层机制的实现不变量。
该字段在每种实体上都是可选的。没有跨字段规则的实体完全省略该字段。
断言何时运行
在编译流水线中,断言求值阶段位于 schema 校验与渲染之间:
- 解析:参数校验与插值,然后依据
schema:/usesSchema:/featuresSchema:进行 schema 校验。 - 拓扑构建与图的最终确定:组装图。
- 静态分析:将每个
uses:socket 的选择器与其连接所到达的组件的标签进行比对检查。 - 针对每个实例求值 Component / Feature 断言。
- Recipe 绑定。
- 针对已绑定的实例求值 Recipe / FeatureRecipe 断言。
- 渲染:求值映射模板,生成输出。
两个断言阶段都在任何渲染之前运行——不渲染任何 chart,也不生成任何 Compose 文件。在 Recipe 断言运行之前,唯一会向 provider 询问的是它为每个已绑定节点的资源所起的名称,Recipe 的 provides 可以读取该名称。断言失败会立即以该断言的具体错误消息中止构建;后续步骤不会执行。
两个阶段的划分反映了职责的划分:Component 级规则无论绑定哪个 Recipe 都适用,因此在绑定之前触发;Recipe 级规则在选定某个具体 Recipe 的前提下适用,因此在绑定之后触发。
模板上下文
对于 Component 和 Feature 的 assertions:,模板上下文公开已解析的实例状态:
.values— 开发者的values内容。.infra— 运维的infra内容(来自 Aggregate 或 Release)。.uses— 已解析的uses:连接,每个连接都已按其 socket 的选择器检查过,其形状与作者编写时相同:以 socket 名称为键,每个 socket 下再以其上每个连接的 alias 为键——即作者在该 socket 下为连接起的名称;对于以列表项形式编写的连接,则为其目标。每个连接的条目描述该连接本身,不携带其目标发布的任何内容。target是已解析目标的实例 id,alias重复其作为键的名称,当连接由某个 Feature 附件引入时会出现origin_feature。与它们并列的还有三项信息,其名称与 Recipe 模板在同一连接的.context.uses.<alias>条目上读取它们时所用的名称相同,template-context-contract.md 描述了每项的内容:labels— 目标的标签,绝非断言所在 component 的标签;values,写在该连接上的值;以及features,写在该连接上的附件,以各自填充的 slot 为键。这三项在每个连接上都存在,连接未携带时为空;features下的附件具有下文.features所给出的形状。因此,.uses.<socket>.<alias>.target读取某个连接的已解析目标,.uses.<socket>.<alias>.labels读取该目标的标签;包含多个连接的 socket 为每个连接各保存一个条目;通过此映射去读取目标所发布值的引用会停机,因为条目不携带此类字段。.features— 已解析的附件,以作者为每个附件起的实例名称为键。每个条目携带type(所附加 Feature 的目录 URI)、resolved_version(本次构建绑定的版本)和values(该附件自身的开发者意图内容)。写在该 component 某个连接上的附件不在其中,正如它不在 Recipe 模板的.features中一样:它在其连接下读取,位于.uses.<socket>.<alias>.features.<slot>,形状相同。.metadata— 正在求值的实例:其instance_id、其component类型和resolved_version、其boundary_path,以及本次构建的aggregate_name、aggregate_version和release_version。
对于 Recipe 和 FeatureRecipe 的 assertions:,上下文增加了 Recipe 特有的字段:
.provides— 被求值 component 的已解析provides:值,在断言运行时已计算完毕。目标发布的值不在此界面上;它们改为在渲染上下文中提供给调用方。.locals— Recipe 的局部变量。.recipe.metadata— Recipe 的name和version,以及其capability。.recipe.source— Recipe 的源指针。
字段访问使用标准 Go 模板语法(.values.architecture、.uses.databases.primary.target);按照 Loud Guardrails 契约,停机构造为 {{ fail "message" }}——失败的断言会产生清晰、具体的构建时错误,指明被违反的不变量。
此界面以 missingkey=error 求值。 引用上下文中不存在的键会使构建停机——并指明实体、实例、断言和缺失的键——而不是渲染为空。正是这种严格性使断言值得信赖:如果引用渲染为空,谓词就会与空值比较并通过,一个拼写错误就会悄无声息地使该断言本应强制执行的规则失效。这也意味着裸引用会在任何回退运行之前解析,因此可选字段需要使用能感知存在性的形式;errors/fatal-halts.md 列出了各界面的缺失键策略以及在该策略下可用的形式。
读取 socket 上的连接。 无论 socket 包含什么,其条目的形状都相同:每个连接一个条目,位于其 alias 之下。断言通过 alias 读取单个连接,通过计数或遍历 socket 查看其上的每个连接,并通过检测 socket 自身的键来判断它是否已接线。假设某个 component 的 Aggregate 条目写有
uses: models: local: { target: llama } fast: { target: turbo }以下断言分别以各种方式读取它:
assertions: # The socket's presence: the socket key alone, however many connections it holds. models-wired: | {{- if not (hasKey .uses "models") -}} {{- fail "wire at least one model to the models socket" -}} {{- end -}} # Every connection on the socket: a range visits each one. every-model-distinct: | {{- $seen := list -}} {{- range $alias, $connection := (optional .uses "models" dict) -}} {{- if has $connection.target $seen -}} {{- fail (printf "connection %s points at %s, which another models connection already points at" $alias $connection.target) -}} {{- end -}} {{- $seen = append $seen $connection.target -}} {{- end -}} # One connection, by the alias it was written under; guarded, because the # connection is optional. fast-is-not-local: | {{- with (optional .uses "models" dict) -}} {{- if and (hasKey . "fast") (hasKey . "local") (eq .fast.target .local.target) -}} {{- fail (printf "the fast and local connections both point at %s" .local.target) -}} {{- end -}} {{- end -}}遍历按 alias 的字母顺序访问 socket 的连接——此处 fast 在 local 之前——而不是按 Aggregate 编写它们的顺序。只包含单个连接的 socket 也以同样方式读取:无论旁边是否接有 fast,.uses.models.local.target 都读取 llama,而 .uses.models.target 不指向任何连接,会停机。
component 持有的每个连接在这里都有各自的条目,因为同一 component 的任意两个连接都不会共享 alias——无论在同一 socket 还是两个 socket 上,也无论各自由哪个文档或附件引入。构建会在任何断言运行之前拒绝这样的一对连接,并指明这两个连接以及各自的编写位置。列表中两次命名同一目标就是这样的一对,因为列表项的 alias 就是其目标;component 自身的 local 连接与同一 component 上某个附件的 local 连接并存也是如此。
读取连接携带的内容。 关于连接的规则可以读取其目标是什么、开发者在连接上写了什么以及连接上附加了什么,因此无论哪个 Recipe 绑定,该规则都成立。一个其 models socket 声明了 unauthenticated 值和 credential slot 的 Component,可以在连接既未携带凭据也未选择退出时,拒绝连接到其目录标记为托管服务的目标:
assertions: hosted-model-needs-a-credential: | {{- range $alias, $connection := (optional .uses "models" dict) -}} {{- $hosted := eq (optional $connection.labels "component.aggrega.ai/hosting" "") "managed" -}} {{- $optedOut := optional $connection.values "unauthenticated" false -}} {{- if and $hosted (not (hasKey $connection.features "credential")) (not $optedOut) -}} {{- fail (printf "the models connection %s reaches a hosted model with no credential: attach one under credential, or set unauthenticated: true on the connection" $alias) -}} {{- end -}} {{- end -}}标签从 labels 读取,它属于目标——即模型——而绝非 component 自身;退出选项从连接的 values 读取;凭据是连接 features 下的一个 slot。每一项都使用 optional 或 hasKey 读取,因为目标可能没有这样的标签,连接也可能没有这样的值。标签的含义是目录的约定:构建只携带该字符串,由断言决定其含义。
断言的 .uses 不是 Recipe 模板的 .context.uses,为其中一个编写的引用不能用于另一个。 渲染上下文携带同一组边的更丰富投影:仅以 alias 为键,socket 名称作为条目上的一个字段,每个目标发布的值嵌套在 provides 下——因此 Recipe 模板读取 .context.uses.<alias>.provides.<name>,而断言读取 .uses.<socket>.<alias>.target。两种视图都携带的信息名称相同但路径不同:.context.uses.<alias>.labels 与 .uses.<socket>.<alias>.labels 是同一目标的标签,values 和 features 同样在两者上读取同一连接。两个断言阶段都在渲染之前求值,这就是为什么断言对边的视图不携带其目标发布的任何内容,也是为什么边上的附件不携带 provides。
关于更完整的模板上下文形状及各字段的可用性语义,请参阅 template-context-contract.md。
此表面上的数字
断言读取作者编写的数字的方式与值模板完全相同——参见值模板中的数字:
- 比较。 六个比较函数按值读取两个数字,无论各自由哪种类型承载:
lt .values.replicas 1.5和eq .values.replicas 3.0在这里的结果与在值模板中相同,作者编写的0.1与断言中写的0.1是eq的,而将数字与带引号的文本比较时,会以相同的措辞中止。 - 空值。 作者编写的
0是空的:对if和with为假,对empty为真,并会被default替换。询问作者是否写了某个值(包括0)的规则,应使用存在性辅助函数来询问:对于作者编写的0,hasKey .values "replicas"为真,optional .values "replicas" 1返回0。询问值是否为零的规则则进行比较:eq .values.replicas 0。存在与空值将这两个问题并列说明。 - 打印。
fail消息打印的数字,读起来与在值模板输出中相同:整数按整数打印,因此printf "%d"打印其数字;其他任何数字以最短的精确十进制形式打印,因此作者编写的0.0000001读作0.0000001。
Component / Feature 断言——架构不变量
这些断言表达的规则无论由哪个 Recipe 绑定该 Component 都成立。规则是契约的属性,而不是实现的属性。
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: core/datastore/mariadb version: 1.0.0 labels: component.aggrega.ai/type: stateful-server component.aggrega.ai/category: datastorespec: schema: values: architecture: { type: string, enum: [standalone, replication], default: standalone } primary: replicaCount: { type: integer, min: 1, max: 9, default: 1 } secondary: replicaCount: { type: integer, min: 0, max: 9, default: 0 }
assertions: # Replication mode requires at least 2 secondary replicas. replication-needs-two-secondaries: | {{- if eq .values.architecture "replication" -}} {{- if lt .values.secondary.replicaCount 2 -}} {{- fail "architecture=replication requires secondary.replicaCount >= 2" -}} {{- end -}} {{- end -}}
# Total node count limit for safe replication coordination. total-node-count-within-cap: | {{- $total := add .values.primary.replicaCount .values.secondary.replicaCount -}} {{- if gt $total 9 -}} {{- fail (printf "total node count must not exceed 9; got %d" $total) -}} {{- end -}}这两条规则都表达 MariaDB 契约的属性。无论绑定的是哪个 Recipe——Bitnami chart,还是手工编写的替代实现——这些规则都适用。
{{- ... -}} 空白控制很重要:断言模板不产生输出,只通过 {{ fail }} 产生副作用。去除空白可使渲染后的模板主体在成功情况下保持为空。
Recipe / FeatureRecipe 断言——实现不变量
这些断言表达的规则适用于该 Recipe 所引用的特定 chart 或模块。规则是实现的属性,而不是契约的属性。
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: bitnami/datastore/mariadb/k8s version: 1.0.0spec: capability: helm implements: core/datastore/mariadb:^1.0.0 source: # Keys this provider defines for itself; a source the build fetches is written as { kind, url, version } instead. chart: oci://registry-1.docker.io/bitnamicharts/mariadb version: "20.0.0"
valuesMapping: $import: BitnamiHelpers#/mappings/MariaDBBitnamiCore
assertions: # Bitnami chart 20.x requires an explicit ServiceMonitor namespace when # replication and metrics scraping are both enabled. service-monitor-namespace-required: | {{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}} {{- if not .values.metrics.serviceMonitor.namespace -}} {{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}} {{- end -}} {{- end -}}
# ARM-node incompatibility. arm-rejects-hard-anti-affinity: | {{- if and (eq .values.primary.podAntiAffinityPreset "hard") (eq .infra.cpu_arch "arm64") -}} {{- fail "Bitnami MariaDB 20.x is incompatible with ARM nodes when podAntiAffinityPreset=hard; use 'soft' or omit" -}} {{- end -}}每条规则都特定于 Bitnami chart 20.x 这一实现。如果绑定的是另一个 MariaDB Recipe(手工编写的 chart 或其他替代实现),这些规则就不适用。Component 级别的规则(replication-needs-two-secondaries、total-node-count-within-cap)仍然适用,因为它们是契约的属性。
为什么 Component 断言与 Recipe 断言相互分离
这两种角色看起来相似(都对跨字段规则执行 {{ fail }} 中止),但职责划分是承重性的:
- Component 断言是契约的一部分。 当开发者编写带有
secondary.replicaCount: 1的architecture: replication时,无论绑定哪个 Recipe,构建都会拒绝。将来出现的替代 Recipe 也不会改变这一点。 - Recipe 断言是实现的一部分。 当架构师选择 Bitnami chart 20.x 作为 Recipe 时,该 chart 有其特定的怪癖(
serviceMonitor.namespace要求、ARM 节点缺陷)。这些不适用于其他 chart。
把两类规则都放在 Component 上会使契约与其实现纠缠在一起:Component 需要引用其绑定的 Recipe 才能知道要执行哪些实现规则,从而破坏 Component 与 Recipe 的分离。将规则拆分到各自的自然位置可以保持职责模型清晰。拆分的运行时开销可以忽略不计;两个阶段都在渲染之前运行,并以相同的 Loud Guardrails 诊断 E0033 中止,指出实体、实例和规则。
fail 消息约定
{{ fail "..." }} 的参数是面向用户的构建时错误。约定如下:
- 指明约束——“architecture=replication requires secondary.replicaCount >= 2”。
- 在相关时指明值——“total node count must not exceed 9; got 12”。
- 在可能时给出修复建议——“use ‘soft’ or omit the field”。
- 避免术语行话——读者是编写该 Aggregate 的开发者,而不是编写该断言的架构师。
对于较长或包含值的消息,使用 printf:
{{- fail (printf "field %s exceeds limit: got %d, max is %d" .field .value .max) -}}编译器以 Loud Guardrails 错误格式呈现该消息,其中包含实体名称、断言的源位置以及失败消息。该诊断足够具体,开发者可以据此定位并修复根本原因。
作者声明为 sensitive: true 的值,在该消息中凡被引用之处都显示为 <redacted>,因此在消息中写出已声明字段的值是安全的:诊断仍会指明规则和字段,只有值被隐去。如果某个断言的结果取决于这样一个值的内容(例如与字面量比较、前缀测试),它报告的是其失败文本已被隐去,而不是它的消息。完整规则见 vocabulary/compact-form-authoring.md 中的“What a refusal says about a declared value(拒绝对已声明的值说明了什么)”。
assertions: 不能替代的内容
assertions: 是跨字段规则的归属之处。它不能替代:
schema:中的 JSON Schema 约束——单字段规则(范围、模式、枚举、格式、类型)应使用 JSON Schema 的原生关键字表达。- 紧凑形式的
validate:字段——作用范围为单个字段的自定义谓词。规则适用于某个特定字段时,使用validate:;规则涉及多个字段、且没有哪个字段是“被校验的那个”时,使用assertions:。 - 紧凑形式的
when:字段——条件化的结构(某个子树的约束是否生效)。结构变化使用when:;当值的组合无效、且更适合用自由形式的谓词表达时,使用assertions:。 - 运行时检查——
assertions:仅在编译时运行。任何依赖运行时集群状态的内容(实时 IP、vault 内容、运行时 pod 状态)都必须表达为确定性的指针字符串(参见 AOT 纯度契约)。
示例详解
最简示例——单条架构规则
spec: assertions: replication-needs-two-secondaries: | {{- if and (eq .values.architecture "replication") (lt .values.secondary.replicaCount 2) -}} {{- fail "replication requires secondary.replicaCount >= 2" -}} {{- end -}}中等规模——多规则 Component 契约
spec: assertions: # Replication minimum. replication-needs-two-secondaries: | {{- if eq .values.architecture "replication" -}} {{- if lt .values.secondary.replicaCount 2 -}} {{- fail "architecture=replication requires secondary.replicaCount >= 2" -}} {{- end -}} {{- end -}}
# Total node limit. total-node-count-within-cap: | {{- $total := add .values.primary.replicaCount .values.secondary.replicaCount -}} {{- if gt $total 9 -}} {{- fail (printf "total node count exceeds 9: got %d (primary=%d, secondary=%d)" $total .values.primary.replicaCount .values.secondary.replicaCount) -}} {{- end -}}
# A ServiceMonitor scrapes the metrics exporter, so it needs one. service-monitor-needs-metrics: | {{- if and .values.metrics.serviceMonitor.enabled (not .values.metrics.enabled) -}} {{- fail "metrics.serviceMonitor.enabled=true requires metrics.enabled=true" -}} {{- end -}}生产级——带实现规则的 Recipe
spec: assertions: # Bitnami 20.x: serviceMonitor namespace requirement. service-monitor-namespace-required: | {{- if and (eq .values.architecture "replication") .values.metrics.serviceMonitor.enabled -}} {{- if not .values.metrics.serviceMonitor.namespace -}} {{- fail "Bitnami MariaDB 20.x requires metrics.serviceMonitor.namespace when architecture=replication and metrics.serviceMonitor.enabled=true" -}} {{- end -}} {{- end -}}
# TLS certificate consistency. tls-needs-both-certificate-files: | {{- if .values.tls.enabled -}} {{- if not (and .values.tls.certFilename .values.tls.certKeyFilename) -}} {{- fail "tls.enabled=true requires both tls.certFilename and tls.certKeyFilename" -}} {{- end -}} {{- end -}}
# Replication-mode storage class consistency. replication-needs-one-storage-class: | {{- if eq .values.architecture "replication" -}} {{- $primaryClass := .values.primary.persistence.storageClass -}} {{- $secondaryClass := .values.secondary.persistence.storageClass -}} {{- if and $primaryClass $secondaryClass (ne $primaryClass $secondaryClass) -}} {{- fail "replication mode requires primary and secondary to use the same storageClass" -}} {{- end -}} {{- end -}}工具集成
aggrega build在 schema 校验与渲染之间求值断言;失败的断言会以该断言的{{ fail }}消息终止构建。aggrega validate在渲染之前执行同样的正确性检查,但不写出制品——对于源未被获取的 Recipe,它会围绕一个合成的最小 Aggregate、Manifest 和 Release 驱动真实的编译流水线,因此格式错误的断言模板或引用了未知字段的断言会作为正确性错误暴露出来;源已被获取的 Recipe 的断言由构建来求值。其中调用fail的断言会被报告为带有其消息的警告,且检查仍然通过:合成的 Release 包含的是占位符和默认值,而不是真实 Release 所设置的值,因此对该断言的判定留给构建——参见失败的断言是警告。(aggrega lint涵盖的是发布约定,而不是断言的正确性。)- 支持 Sprig 模板的 IDE 会高亮
.values.X引用;配置了 IDE 集成后,悬停文档会解析到 schema 定义。