社会契约(Social Contracts)
Aggrega 在设计上是一个不预设立场的编译器。根据 architecture/05-invariants.md 中记录的基础不变量,编译器解析 YAML、遍历图、计算标签交集,并在组件之间传递字符串——但它不会监管开发者在 values、parameters、infra、provides 或 locals 中放入什么内容;它不强制执行命名约定、端口约定或架构师自创的语义标签;它也不会根据名称猜测组件的用途。许多听起来像编译器规则的纪律,实际上是社会契约:依靠编写约定来维护的最佳实践,而不是由 schema 或运行时强制执行。
**这种中立止于何处值得明确说明,因为界线只有一条,而且很容易被过度解读。**少数键属于 Aggrega 自身——它们是保留键,其可取的值已写入已发布的 schema——schema 确实会检查这些键,方式与检查任何其他已声明字段相同。为平台自身定义的键声明取值集合,并不是编译器在解读你所写内容的含义,而是平台在说明其自身的键代表什么。你在自己的键下编写的一切内容,仍然完全如本页所述,不受监管。
本页是该语言社会契约的权威清单。通过本页了解这些契约的作者,可以理解为什么编译器会接受一个按约定来说格式错误的构建(它确实会接受——编译器不解读约定),以及发现违规的责任在于何处(编写纪律、评审者的关注,或由 aggrega lint 运行的 linter 插件)。
三类约束
Aggrega 的约束按约束的执行方式分为三类。这一分类之所以重要,是因为违反约束时,每一类的失败模式各不相同。
由 schema 强制执行
此类纪律在加载时由 JSON Schema 2020-12 校验强制执行(实体信封的 JSON Schema,以及 Component 和 Feature 实体上支柱级别的 schema: 声明)。违反时会在构建推进之前产生致命中止,编译器拒绝继续。试图违反由 schema 强制执行的纪律的作者会看到一条明确的校验错误,指向相应的字段和约束。
示例:实体信封的必填字段(apiVersion / kind / metadata.name / metadata.version);metadata.version 上的 SemVer 正则表达式;保留的 component.aggrega.ai/type 标签上的封闭取值集合;Release schema 对 values: 块的机械禁止(依据不变量 5);Release 上 extends 与 aggregate 同时出现时的拒绝(单一事实来源不变量);强制执行输入种类组合契约的 Recipe 形状规则。
由 schema 强制执行的纪律是该语言所提供的最强保证。编译器拒绝渲染任何违反它们的内容。
由策略插件强制执行
此类纪律由在某个文档所述插槽点运行的 Wasm 插件强制执行(拓扑构建阶段的治理 label-transform 角色;静态分析阶段的治理 ir-verdict 角色;带外的 linter 插槽)。根据插槽的门控语义,违反时会产生中止构建的策略失败(带内插槽)或建议性警告(带外插槽)。
只有在运行着检查某项纪律的插件时,该纪律才会以这种方式得到强制执行:Wasm 运行时会在文档所述的插槽点调用插件,而没有任何插件检查的纪律仍然只是约定。由 aggrega lint 运行的发布 linter 会检查本页中一项约定的一部分——参见 由 linter 规则检查的约定。发布 linter 没有任何规则检查密闭性(根据 templates/sprig-functions.md 中关于确定性的注意事项,Sprig FuncMap 暴露了会破坏确定性输出的辅助函数)或云资源命名(即 valuesMapping: 输出引用了云资源名称字段却没有插入 release_name / instance_id 的 Recipes,参见 entities/recipe.md “Cloud-resource naming discipline”);你自己的 linter 插件可以检查其中任一项。
关于 Wasm 插件的契约接口以及放置准则(linter 插槽与治理裁决角色之间的选择),参见 plugins/plugin-contract.md。
由约定维持
此类约束仅靠编写规范加上审阅者的关注来维护。编译器不强制执行;没有 schema 拒绝违规;也没有 Wasm 插件标记它。作者从文档中学习这些约束,因为架构形态依赖于它们而遵循它们,并依靠 PR 审查来发现疏漏。违反时不会产生任何编译期信号——构建成功,就编译器所知渲染输出也能正常工作,只有当下游工具或运行时行为依赖该约定时,违规才会显现。
由约定维持的纪律是作者必须从文档中学习的关键清单。编译器不解释它们;弄错它们不会破坏构建,但会破坏 Aggrega 所依赖的架构形态。本页的主体部分记录的就是它们。
各项约定
以下社会契约由约定维持。每个条目说明该纪律、记录该约定的位置,以及违反时的失效模式。每个条目无论位于何处都保留其编号:契约 3,即保留前缀纪律,其注解键由一条 linter 规则检查,在 由 linter 规则检查的约定 下说明。
1. 选择适合组件的运行类型
保留的 component.aggrega.ai/type 标签说明一个组件属于哪类事物,取值来自一个封闭的通用云原语集合:server、worker、task、function、stateful-server、resource。该集合的成员资格由 schema 强制执行,而不是由约定维持。 Aggrega 定义了这个键及其接受的值,Component schema 枚举了这些值,携带其他值的文档在加载时即被拒绝——E0215,即 entity-envelope-invalid 条件,会指出该标签并列出它接受的值。这种拒绝正是本条目不涵盖的内容。
仍属于约定的是:这些值中哪一个适合你面前的组件。没有任何检查会确认关系型数据库被标记为 stateful-server 而不是 server,或者队列消费者是 worker 而不是 task;选择器会评估它找到的任何值,而不对其赋予含义。编写 Component 的架构师选择描述基础设施必须如何对待它的值,而下游的选择器、策略插件和 Wasm 渲染插件都依赖这一选择是真实的。
按你自己的维度分类。 该封闭集合只约束这一个保留键,不涉及其他。如果目录需要 Aggrega 未定义的分类——层级、数据区域、服务等级,或对运行原语更细的划分——就在保留键旁添加自己的标签键。Component schema 接受任何值为字符串的其他标签键,同一套选择器机制也会读取它,因此 acme.aggrega.ai/storage-tier: oltp 可以与 component.aggrega.ai/type: stateful-server 并存,Feature 的 appliesTo 或插槽的 selector 可以针对其中任意一个。扩展应发生在你自己的键上,而绝不在 Aggrega 的键的值内部。
记录位置: architecture/02-ecosystem-philosophy.md(运行本体)+ labels-and-annotations.md(前缀纪律)+ errors/sentinels.md(E0215)。
失效模式: 来自该集合但不适合组件的值会误导所有读取该标签的环节。被标记为 server 的数据存储会被选择 stateful-server 的 Feature 或插槽拒绝——中止信息指出的是选择器,而不是错误的标签——而读取该标签的策略插件或渲染插件会将其当作无状态计算处理。在只有这类读取方看到它的情况下,构建会成功;错误只有在渲染产物到达集群后才会显现。
2. 三桶 .context.annotations.* 分离
级联注解落入三个具名桶——.context.annotations.release、.context.annotations.catalog、.context.annotations.aggregate——每个承载不同的意图。纪律目标:release 表示“该组件在何处运行,由 Ops 管理”;catalog 表示“该组件是什么,由架构师编写”;aggregate 表示“该组件做什么,由开发者编写”。
编译器不强制执行桶的边界。三个桶共享扁平的 string → string 形态;Recipe 的模板可以读取全部三个,没有任何机制阻止 Release 边界注解被解读为认知元数据,或目录注解被路由到 infra: 中。这种分离依靠作者把注解写入正确的桶、依靠评审者发现跨桶泄漏来维持。
记录位置: labels-and-annotations.md(三桶分离是一项 Social Contract)。
失效模式: 依赖桶意图区分的路由逻辑(例如,Recipe 将 .context.annotations.release.aggrega.ai/region 路由到 Terraform 的 region 字段)会静默消费桶中出现的任何注解,而不论其编写意图。构建成功;渲染输出可能携带语义错误的值。
4. Recipe provides: 自包含
Recipe 的 provides: 模板只闭包节点自身的数据——.values、.infra、.context.instance_id、.context.rendered_name(当节点的 provider 报告该值时)、节点已解析的 .locals,以及静态字符串。禁止引用 .context.inject 和 .context.uses,因为 provides 求值以任意顺序运行这些模板;读取跨节点数据会使其与拓扑迭代顺序耦合,而设计有意避免这一点。.locals 处在可用范围之内:节点的 locals 在同一阶段的前导部分、先于其 provides 解析,且属于节点本地,因此读取它们不会带来任何顺序上的代价。引用 locals 块未声明的键会导致中止。
这是一条分为两半的规则,每一半都指明在何处检查。编译器检查前一半:provides 求值会在模板执行前,根据其上下文定义的根的正向允许列表检查每个模板,因此读取 .context.inject / .context.uses 会以明确的错误中止,而不是渲染为空;该规则也记录在 templates/expansion-matrix.md 第 6 行。约定维持后一半:更广泛的模式(provides 是公开的;locals 是私有的)以约定为依托。
记录位置: templates/expansion-matrix.md 第 6 行 + vocabulary/data-pillars.md “provides: 与 locals:——公开面与私有面”。
失效模式: 当被禁止的引用直接出现在 provides: 中时,编译器会在模板求值时检测到并中止构建。更广泛的公开与私有纪律(不要通过 provides: 键暴露内部状态)仅靠约定——把 provides: 当作 Recipe 内部命名空间的作者,会产生调用方所依赖的契约;重构因此成为破坏性变更。
5. 确定性——渲染路径模板中的非封闭辅助函数
Aggrega 的确定性输出不变量(architecture/05-invariants.md 中的不变量 8)要求字节相同的输入产生字节相同的输出。Sprig 的完整 FuncMap 暴露了读取环境状态的辅助函数(挂钟读取器 now / date;随机生成器 randAlpha / uuidv4;环境变量读取器 env / expandenv;网络解析器 getHostByName)。在参与渲染输出的模板中调用这些辅助函数的作者,会破坏确定性契约。
编译器不会检测或阻止对非封闭辅助函数的使用。Sprig FuncMap 按照 templates/sprig-functions.md “Determinism caveat” 暴露这些函数;该纪律由作者在渲染路径模板中避免使用这些辅助函数、由审阅者在 PR 审阅时发现其使用来维护。
文档位置: templates/sprig-functions.md “Determinism caveat”。
失败模式: 相同输入的多次运行产生不同的构建输出。这种不一致会在 GitOps diff 时暴露,此时下游工具(ArgoCD、Flux)会发现已提交的 manifest 与集群状态之间出现意外漂移;或者在审计时暴露,此时对相同输入的两次编译产生了不同的制品。
发布 linter 没有任何规则检查模板中对非密闭辅助函数的调用。辅助函数的名称写在模板中,因此你自己的 linter 插件可以找到它(参见 由 linter 规则检查的约定)。
6. 支柱边界(是路标而非围墙)
支柱边界是编写纪律,而非语言强制。模板引擎允许在每个位置跨支柱读取,除非自包含规则明确禁止(例如 Recipe 的 provides: 和 source: 读取 .context.inject / .context.uses)。作者应当:
- 读取
.values获取认知载荷(开发者编写的意图)。 - 读取
.infra获取物理规格(Ops 编写的规格)。 - 读取
.context.uses.<alias>.provides.<key>获取跨组件的指针字符串。 - 读取
.context.inject获取注水后的交付管道。
模板引擎不会拦截读取。读取 .infra.replicas 来驱动某个 values: 字段的 Recipe 模板可以正常工作;没有任何机制阻止这种跨支柱路径。该纪律的目标是路标——边界描述的是编写意图(谁拥有数据),而非运行时限制。
文档位置: vocabulary/data-pillars.md “Pillar boundaries and authoring discipline”。
失败模式: 跨支柱泄漏——开发者的认知载荷中包含物理规格细节,或 Ops 编写的规格中包含认知元数据。构建成功;随着作者绕过支柱,四域编写分工会逐渐模糊;随着支柱与数据流对应关系的减弱,下游维护会变得更困难。
7. Workload containers.<name>.variables 的双来源语义
variables: 映射通过 Go 模板表达式混合两种不同的数据来源:开发者支柱字面量(读取 .values / .infra / .locals 的条目)和跨组件管道数据(读取 .context.inject.env.<KEY> 的条目)。作者根据值是组件本地的还是跨组件派生的,为每个条目选择一种来源。
编译器不区分这两种来源;两者都流入渲染后 Deployment 上的同一个 Kubernetes env: 列表。双来源语义仅存在于编写时——该纪律在于标明意图(这个条目是组件本地的;那个条目是跨组件派生的),以便未来的维护者能看出哪些条目依赖哪些注入注水输出。
文档位置: entities/workload.md “Field-semantics essentials”(variables)。
失败模式: 不区分两种来源的作者会丢失“哪些条目耦合到哪个目标的 provides:”这一追踪线索。重构目标的 provides: 键会静默破坏每个通过注入管道读取的调用方 variables: 条目。
8. 云资源命名纪律
输出云资源名称(S3 存储桶名称、RDS 数据库标识符、IAM 角色名称、CloudFormation 堆栈名称——任何其值在云提供商处占用全局命名空间的字段)的 Recipes 必须将 {{ .metadata.release_name }} 和/或 {{ .context.instance_id }} 拼接到渲染出的名称中,以避免同一 Recipe 在多个 Releases 或组件实例间运行时发生冲突。
编译器不会检查 valuesMapping: 输出中缺少这些插值的云资源名称字段。该纪律由 Recipe 作者(他们知道哪些字段为目标提供商命名全局唯一资源)和审阅者(他们在 PR 审阅时发现未命名资源的模式)维护。
文档位置: entities/recipe.md “Cloud-resource naming discipline”。
失败模式: 同一 Aggregate 的两个 Releases(prod-billing 和 staging-billing)都尝试部署具有相同全局名称的资源;第二次部署在运行时因云端拒绝而失败。Aggrega 构建成功;部署失败仅在应用第二个 Release 时才暴露。
发布 linter 没有任何规则检查云资源名称字段是否带有所需的插值;你自己的 linter 插件可以做到(参见 由 linter 规则检查的约定)。
9. Component 粒度——每个 Component 一个内聚服务
一个 Component 建模一个内聚服务——单个对外暴露的服务,或者一个服务的 workload 连同其仅供内部使用的辅助 workload。当某个 chart 捆绑了其他组件可以有意义地单独 use 的服务时——尤其是 Aggrega 已将其建模为独立 Component 的外部基础设施,例如数据库、缓存或消息代理——标准库会将按服务划分的 Components 组合成一个子 aggregate 模块(spec.aggregates + exportedComponents),而不是将整个产品包装成一个不透明的 Component。该纪律是:在一个 Component 内包含多个 workload 没有问题;能否独立使用才是将一个 Component 拆分为一个栈的分界线。
编译器与这种粒度无关。它渲染任何通过 schema 校验的内容——不会检查一个 Component 的 Recipe 捆绑了多少个服务,也不会检查其中某个服务是否可独立使用。将一个五服务产品包装成单个 Component 的作者,会得到一个编译器接受并毫无异议地渲染的 Component;该约定由编写纪律和审阅者的关注来维护。
文档位置: ../../architecture/06-data-taxonomy-and-composition.md(每个 Component 一个内聚服务——单 workload 边界)。
失败模式: 单体式多服务包装可以成功构建,但被捆绑的服务对拓扑、选择器和策略不可见——它们无法被独立扩缩、替换或依赖。之后将该单体重构为按服务划分的 Components,对每个引用了该单个包装节点的使用方而言都是破坏性变更。
为什么存在约定
这些约定在设计上都是编写纪律,尽管 schema 或 Wasm 策略可以强制执行其中任何一项。各类契约的理由如下:
可扩展性。 保留前缀规范(契约 3)描述的是标准库的词汇,而不是所有有效词汇的全集。企业目录会编写自己的前缀和标签键来扩展标准库;用 schema 强制执行前缀约定会把“标准库的规范”变成“语言唯一允许的形态”——这正是架构有意避免的墙。运维类型轴(契约 1)在另一个层面上保持同样的可扩展性:Aggrega 定义的保留键带有一个封闭的、由 schema 强制执行的取值集合,目录通过在其旁边添加自己的标签键来扩展,而不是在 Aggrega 的键中添加值。schema 检查的是它所拥有的那一个键的取值集合;保持开放的是其他所有键,目录自己的词汇正位于其中。
AOT 纯度。 云资源命名纪律(契约 8)和确定性纪律(契约 5)需要内省模板内容,才能判断某个字段是云资源名称还是非密闭辅助函数调用。AOT 纯度(不变量 2)使编译器不依赖运行时状态;静态模板内省是可行的(linter 插件会按编写原样读取实体的模板),但在核心编译器内部执行它会把编译器内部逻辑与各领域的编写关注点耦合在一起。依据不变量 6(Wasm ABI 边界),架构将这些检查移出编译器,放入 Wasm 插件中。
编写灵活性。 支柱边界规范(契约 6)和双来源 variables 语义(契约 7)描述的是编写模式,而不是运行时约束。同样的模板语法既可以表达遵守规范的模式,也可以表达违反规范的模式;把规范变成运行时检查,就要求编译器解读它无法获知的编写意图。架构将该约定视为作者从中学习的文档,而不是运行时不变式。Component 粒度(契约 9)也属于此类:企业可以按其目录偏好的任何粒度封装产品,而编译器——依据不变式 1,对内容保持中立且不预设立场——无法知道某个打包的 workload 是否可以独立使用,因此“一个内聚服务”的边界仍是编写规范,而不是 schema 墙。运维类型的选择(契约 1)也是同样的形态:schema 决定存在哪些值,但哪个值描述某个给定组件,是关于基础设施必须如何对待它的建模判断,Recipe 或 values 块中没有任何内容能告诉编译器这个判断是否正确。
分为两半的强制执行。 Recipe provides: 自包含(契约 4)部分由编译器强制执行——渲染路径会检测 provides: 模板中对 .context.inject / .context.uses 的读取并中止。更广泛的公开与私有纪律(不要暴露内部状态)则以约定为依托,因为没有编写意图,编译器无法确定哪些字符串应保留在 Recipe 内部。
这三种途径很重要,因为每一种都表明了捕获违规的责任所在。由 schema 强制执行:编译器。由策略插件强制执行:检查它的插件(在有插件运行的地方)。由约定维持:作者和评审者。理解这些途径的作者会明白,哪些错误会被编译器捕获,哪些会悄无声息地流入下游工具或运行时。
由 linter 规则检查的约定
由 aggrega lint 运行的发布 linter 会部分检查本页中的一项约定:下文契约 3 的注解键。其发现是建议性的,而该约定中它未涉及的部分与上面各条目一样由约定维持。
发布 linter 没有任何规则检查本页中的其他约定。其中有两项可以由 linter 规则检查,因为违规就写在实体中:确定性(契约 5)——调用非密闭辅助函数的模板——以及云资源命名(契约 8)——命名云资源却没有插入 release_name / instance_id 的 valuesMapping: 输出。保留前缀下的标签键(契约 3)也可以。工作区可以在 plugins.linter 下、在发布 linter 旁挂接自己的 linter 插件,以检查其中任何一项;The discipline rules 列出了发布 linter 所带的规则。
其他约定(1、2、4、6、7、9)取决于作者的本意,而任何规则都无法从所写内容中读出这一点。分桶分离由可扩展性驱动(企业目录会进行覆盖)——schema 强制执行会与这种灵活性相冲突。运营类型轴在 schema 确定取值集合之后剩下的部分——挑选适合该组件的原语——由编写意图驱动:编译器无法区分选得好的运营类型和选得差的运营类型,因为两者都是它接受的值。支柱边界纪律和双来源 variables 语义由编写意图驱动——编译器无法仅凭模板语法判断意图。Recipe 的 provides: 自包含性部分得到强制执行;更广泛的公有与私有纪律取决于作者打算将哪些键保留为内部,而 Recipe 中没有任何内容说明这一点。Component 粒度同样由编写意图驱动——一个捆绑的工作负载能否独立使用,是编译器无法从 Recipe 内容中读出的建模判断。
3. 保留前缀纪律
注解和标签键遵循 <namespace>/<name> 形态。五个保留前缀带有特定的编写规则:aggrega.ai/(仅限平台)、feature.aggrega.ai/(官方 Feature 快捷方式)、component.aggrega.ai/(Component 固有特性)、aggregate.aggrega.ai/(Aggregate 模块身份),以及 <any-other-domain>/(企业/社区)。
编译器不会拒绝在目录实体或 Release 上以保留前缀编写的注解;只有声明 aggrega.ai/ 下某个键的 Manifest 注解绑定或 Recipe 输出标签才会中止构建。企业在平台词汇之外声明 aggrega.ai/internal-billing-tag: "...",会产生一个编译器接受并通过桶系统级联的注解;之后引入真正 aggrega.ai/internal-billing-tag 的平台更新会静默冲突。
记录位置: labels-and-annotations.md(前缀纪律)+ providers/well-known-annotations.md。
失效模式: 保留前缀下的自定义注解会与将来同名的平台注解冲突;平台预期的行为会根据顺序静默覆盖企业编写的值,或与之并存。
由 aggrega lint 运行的发布 linter 会将目录实体上位于 aggrega.ai/ 下但不属于平台知名注解的注解键,以及 Feature 之外的实体上位于 feature.aggrega.ai/ 下的注解键,标记为建议性发现(E0277)。标签键、其他保留前缀,以及实体 metadata.annotations 之外的注解(例如 Release 写入的注解)不会被检查,因此对它们而言,该纪律仍然只是约定。
交叉引用
architecture/05-invariants.md— 八条奠基不变量,它们是 Aggrega “编译器对内容保持中立”这一表述的基础;每项约定都与其中一条或多条存在张力。architecture/02-ecosystem-philosophy.md— 运维本体论的完整设计依据。vocabulary/labels-and-annotations.md— 作为社会契约的三分桶划分;保留前缀纪律。vocabulary/data-pillars.md— 作为路标的支柱边界;provides:与locals:的公有与私有之分。templates/sprig-functions.md— 列出非封闭辅助函数的确定性注意事项。entities/recipe.md— 云资源命名纪律及完整示例。entities/workload.md— Workloadvariables:的双来源语义。templates/expansion-matrix.md— 作为编译器强制规则的 Recipeprovides:自包含性。plugins/plugin-contract.md— linter 插槽的放置准则。cli/aggrega-lint.md— 发布 linter 的规则,以及如何挂接你自己的 linter。