contracts

README

Truzhen Contracts

Truzhen 主权事务操作层的契约 SDK：纯接口、类型与 JSON Schema，零反向依赖。

github.com/truzhen/contracts 是 Truzhen 三仓架构的契约层，定义基座与包之间一切跨边界的数据形状（候选信封、门控决议、回执、注册切片、ReadModel 投影、监控事件、三主线引用等）以及机器可校验的 JSON Schema。它只声明形状，不含任何实现（无 DB、无网络、无副作用），因此谁都可以安全依赖它，而它谁都不依赖。

依赖方向（单向不可逆）

┌─────────────────────┐   implements   ┌──────────────────────┐   faces   ┌────────────────────┐
│ truzhenos (基座·私有) │ ─────────────▶ │ truzhen-contracts    │ ◀──────── │ truzhen-packs      │
│ 实现契约             │                │ 纯接口/类型/Schema    │           │ 面向契约           │
└─────────────────────┘                └──────────────────────┘           └────────────────────┘
                          契约零反向依赖：不 import 基座、不 import 包

• 基座（github.com/lights314/truzhenos，私有）实现这些契约。
• 包（github.com/truzhen/packs，开放）面向这些契约编写，物理上 import 不到基座内部。
• 契约本身零反向依赖：只依赖 Go 标准库，不依赖基座或包。可用 go list -deps ./... 验证。

作为 SDK 使用

import (
    "github.com/truzhen/contracts/base"
    "github.com/truzhen/contracts/candidates"
    "github.com/truzhen/contracts/receipts"
)

go get github.com/truzhen/contracts@latest

子包总览

完整清单见 MODULES.md。核心：base/（主权门控核心类型）、candidates/（AI 候选域）、gates/（门控裁定）、receipts/（回执/审计）、spines/（事务/意图/证据三主线）、registry/、readmodels/、monitoring/、secrets/（secret 引用契约，不含真凭据）、events/、modules/。

版本策略

遵循 SemVer。契约是跨仓边界：破坏性变更（删字段、改语义、改必填）必须升 major；新增可选字段升 minor。基座与包通过各自 go.mod 的 require 钉版本协同演进。

设计原则

1. 纯形状：只有 type、const、接口与 JSON Schema；任何带 DB / 网络 / 文件 / 时间副作用的代码不属于本仓。
2. 零反向依赖：CI 与 go list -deps 双重把守，契约不得 import 任何实现仓。
3. 机器可校验：*.schema.json 经 embed.go 嵌入，基座与 CI 用它校验产物，而非在代码里重复声明形状。

License

Apache-2.0。

Documentation

Overview

Package contracts embeds the machine-checkable JSON Schemas so Go services and CI tests can validate produced artifacts against the canonical contract files instead of re-declaring the shapes in code (T08 阶段2：契约收敛， contracts 校验进 CI).

Index

• Variables
• type KnowledgeMountReadModel
• type KnowledgeMountStatus
• type KnowledgeScopeDeclaration

Variables

var CandidateEnvelopeSchemaJSON []byte

CandidateEnvelopeSchemaJSON is contracts/candidate-envelope.schema.json （candidates.CandidateEnvelope 的 JSON 表达，client layer 候选卡面向、CI 校验； T12 阶段A：client layer 契约面补全）。

var FlowViewSpecSchemaJSON []byte

FlowViewSpecSchemaJSON is contracts/flow-view-spec.schema.json.

var IntentClassificationSchemaJSON []byte

IntentClassificationSchemaJSON is contracts/spines/intent-classification.schema.json.

var IntentEventSchemaJSON []byte

IntentEventSchemaJSON is contracts/spines/intent-event.schema.json.

var IntentInboxItemSchemaJSON []byte

IntentInboxItemSchemaJSON is contracts/spines/intent-inbox-item.schema.json.

var IntentReceiptSchemaJSON []byte

IntentReceiptSchemaJSON is contracts/spines/intent-receipt.schema.json.

var IntentToCandidateResultSchemaJSON []byte

IntentToCandidateResultSchemaJSON is contracts/spines/intent-to-candidate-result.schema.json.

var ReceiptEnvelopeSchemaJSON []byte

ReceiptEnvelopeSchemaJSON is contracts/receipt-envelope.schema.json （receipts.ReceiptEnvelope 的 JSON 表达，client layer 回执卡面向、CI 校验； T12 阶段A：client layer 契约面补全）。

var SceneFlowSpecSchemaJSON []byte

SceneFlowSpecSchemaJSON is contracts/scene-flow-spec.schema.json.

var ScenePackSpecSchemaJSON []byte

ScenePackSpecSchemaJSON is contracts/scene-pack-spec.schema.json.

var TransactionObjectProjectionSchemaJSON []byte

TransactionObjectProjectionSchemaJSON is contracts/transaction-object-projection.schema.json （事务对象 05 BusinessObject 的前端只读投影 DTO 契约，client layer 渲染事务对象卡的单一来源； T12 阶段A：client layer 契约面补全）。

var VisualUnitSpecSchemaJSON []byte

VisualUnitSpecSchemaJSON is contracts/visual-unit-spec.schema.json （前端 7 类主权视觉单元封顶规格契约，client layer 多端单一来源； T12 阶段A：client layer 契约收敛起步）。

Types

type KnowledgeMountReadModel

type KnowledgeMountReadModel struct {
	MountRef           string               `json:"mount_ref"`
	OwnerID            string               `json:"owner_id"`
	PackRef            string               `json:"pack_ref"`
	PackVersionRef     string               `json:"pack_version_ref"`
	SceneRef           string               `json:"scene_ref,omitempty"`
	KnowledgeScopeRef  string               `json:"knowledge_scope_ref"`
	DisplayName        string               `json:"display_name"`
	Status             KnowledgeMountStatus `json:"status"`
	KnowledgeKinds     []string             `json:"knowledge_kinds"`
	KnowledgeRefs      []string             `json:"knowledge_refs,omitempty"`
	EnabledReceiptRef  string               `json:"enabled_receipt_ref,omitempty"`
	DisabledReceiptRef string               `json:"disabled_receipt_ref,omitempty"`
	LastReceiptRef     string               `json:"last_receipt_ref,omitempty"`
	BlockedReason      string               `json:"blocked_reason,omitempty"`
}

type KnowledgeMountStatus

type KnowledgeMountStatus string

const (
	KnowledgeMountPending  KnowledgeMountStatus = "pending"
	KnowledgeMountActive   KnowledgeMountStatus = "active"
	KnowledgeMountDisabled KnowledgeMountStatus = "disabled"
	KnowledgeMountBlocked  KnowledgeMountStatus = "blocked"
)

type KnowledgeScopeDeclaration

type KnowledgeScopeDeclaration struct {
	ScopeRef       string   `json:"scope_ref"`
	DisplayName    string   `json:"display_name"`
	Description    string   `json:"description,omitempty"`
	SceneRef       string   `json:"scene_ref,omitempty"`
	MountPolicy    string   `json:"mount_policy"`
	KnowledgeKinds []string `json:"knowledge_kinds"`
	Tags           []string `json:"tags,omitempty"`
	Required       bool     `json:"required,omitempty"`
}