contracts

README

徒真（truzhen）Contracts

信任不靠口头承诺，靠白纸黑字的公开契约。

想创作 Pack？从 truzhen/packs 出发 · 本仓回答的是：这套生意为什么做得成

简体中文 · 繁體中文 · English · 日本語 · Русский · Deutsch · Français · Español

---

一个市场最难的问题

徒真（truzhen）让开源作者和行业专家把能力做成 Pack，卖给中国的中小企业。这里有个绕不开的问题：企业凭什么敢安装一个陌生人做的东西？

答案不是「相信作者人品」，而是一套公开、稳定、机器可校验的规则：Pack 能声明什么、必须经过谁的确认、做完之后留下什么凭证——全部写在这个仓库里，作者看得见，企业也看得见。

github.com/truzhen/contracts 就是这套规则的权威源。它只有 Go 类型和 JSON Schema，零实现、零副作用：谁都可以放心依赖它，它不依赖任何实现仓。

三句话说清这套规则

1. AI 和 Pack 只能提建议——所有产出先是「候选」，不直接变成正式结果。
2. 要紧的动作必须过门——发送、执行、写正式数据，都要经过企业负责人确认和平台裁定。
3. 做过的事必须留回执——企业随时可以回放核对发生了什么。

这三条对作者是保护而不是束缚：你的 Pack 不用碰权限、支付和审计，出了问题记录说话，责任分得清。

你什么时候需要看本仓

• 只想做 Pack：先去 truzhen/packs。你只需要知道候选、门控和回执这三条底线，不必先读完整 SDK。
• 要写工具或校验器：用本仓的 Go 类型和 JSON Schema 检查 Pack、候选、回执或市场表面数据。
• 要改跨仓字段：先在本仓定清形状、版本和兼容策略，再让基座、Pack、云端或客户端消费。

这里有什么

契约	它保证的事
Candidate（候选）	AI 的建议和草稿有统一形状，永远和正式结果隔离
Gate（门控）	高风险动作必须回到企业负责人确认和平台裁定
Receipt（回执）	重要动作留下可回放的凭证
Registry / Provider 引用	Pack 只声明需要什么外部能力，不夹带实现
Delegation（委托）	Owner 预授权只能在明确边界内生效；代码执行委托必须额外声明 execution_scope
ReadModel / Surface	界面展示有统一形状，但展示不等于事实
学习与探讨	多供应商合议只暴露受控引用、状态和候选结论；自动化授权、正式动作和回执仍各归 Base、Gateway 与 Ledger
Market 契约面	支付、授权、下载各归其位，云端状态无法在 Pack 里伪造

作为 SDK 使用

如果你只是提交 Pack，通常不需要写这里的 Go 代码；这一段主要给基座、CI、工具作者和高级 Pack 作者使用。

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

go get github.com/truzhen/contracts@latest

依赖方向是单向的：徒真基座实现这些契约，Pack 面向这些契约声明，本仓不依赖任何实现仓（只依赖 Go 标准库，可用 go list -deps ./... 验证）。

当前版本以仓根 VERSION 和已发布 tag 为准。破坏性变更按 SemVer 处理，不把删字段、改必填、改语义伪装成兼容更新。

market.PackSoftwareRequirement 用于声明 Baserow / OCR 等底层软件需求；market.ProviderRequirement 可引用同一固定 Pack 版本内的多个软件需求；market.SoftwareResolutionLock 用于消费 truzhenos resolver 产出的复用、需安装、版本冲突、需隔离、blocked、not_ready 等结果，并可携带 provider family、控制方法和可选执行模式投影。readmodels.PackHandsRequirementReadModel 只向 Owner 解释依赖、解析、阻断和安装候选，不是真相源，不授权安装或执行。contracts 不解析用户本机环境，不保存本机软件事实。

子包速览

核心：base/（主权门控核心类型，含 OwnerDelegationGrant 与可选代码执行委托边界）、candidates/（候选域）、gates/（门控裁定）、receipts/（回执 / 审计）、spines/（事务 / 意图 / 证据三主线）、registry/、readmodels/、monitoring/、secrets/（只有 secret 的引用形状，永无明文凭据）、market/。完整清单见 MODULES.md。

学习与探讨的 Session / Turn / Provider Lane / Automation Grant ReadModel 与 Synthesis Candidate 已在本仓定形；它们不携带问题或供应商原文，且候选永远不能直接成为正式结论。兼容边界见 v0.15.0 说明。

本地优先 AI 事务操作层的 contracts 增量见 v0.16.0 兼容说明。

我们的承诺

• contracts 只定义形状，不给任何 Pack 执行权。
• 明文凭据永不进入本仓。
• 契约稳定可依赖：破坏性变更必须升版本、给迁移说明，不搞突然袭击。
• 本仓零反向依赖，你引用它不会被拖进私有实现。

验证

go build ./... && go test ./... && go vet ./...
go list -deps ./... | grep -E 'lights314/truzhenos|truzhen/packs|truzhen/truzhen-cloud' && echo "违规:反向依赖" || echo "OK:零反向依赖"
python3 -c "import json,glob;[json.load(open(f)) for f in glob.glob('*.schema.json') + glob.glob('spines/*.schema.json')];print('schema JSON 合法')"

想改契约？

先想清四个问题：给谁用、是不是只声明形状、影响哪些消费方、算不算破坏性变更。然后读：

• 贡献指南：CONTRIBUTING.md
• 契约治理总纲：CONTRACTS_GOVERNANCE.md
• Agent 开工纪律：AGENTS.md

License

Apache-2.0。徒真（truzhen）是对外品牌与商标。

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 ContributionReceiptSchemaJSON []byte

ContributionReceiptSchemaJSON is contracts/contribution-receipt.schema.json.

var DeliberationAutomationGrantReadModelSchemaJSON []byte

DeliberationAutomationGrantReadModelSchemaJSON is the projection of a Base-issued bounded automation grant; clients cannot self-mint its refs.

var DeliberationProviderLaneReadModelSchemaJSON []byte

DeliberationProviderLaneReadModelSchemaJSON is the adapter-lane projection with separately declared release eligibility and runtime readiness.

var DeliberationSessionReadModelSchemaJSON []byte

DeliberationSessionReadModelSchemaJSON is the client-safe session projection for the governed multi-provider deliberation flow.

var DeliberationSynthesisCandidateSchemaJSON []byte

DeliberationSynthesisCandidateSchemaJSON describes an AI synthesis output that is permanently candidate_only and non_formal.

var DeliberationTurnReadModelSchemaJSON []byte

DeliberationTurnReadModelSchemaJSON is the client-safe turn projection. It carries a question artifact reference and SHA-256, never question content.

var FaultIncidentSchemaJSON []byte

FaultIncidentSchemaJSON is contracts/monitoring/fault-incident.schema.json.

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 MarketCatalogProductSchemaJSON []byte

MarketCatalogProductSchemaJSON is contracts/market-catalog-product.schema.json.

var MarketCheckoutResultSchemaJSON []byte

MarketCheckoutResultSchemaJSON is contracts/market-checkout-result.schema.json.

var MarketEntitlementSchemaJSON []byte

MarketEntitlementSchemaJSON is contracts/market-entitlement.schema.json.

var MarketLocalGateCheckResultSchemaJSON []byte

MarketLocalGateCheckResultSchemaJSON is contracts/market-local-gate-check-result.schema.json.

var MarketOrderStatusSchemaJSON []byte

MarketOrderStatusSchemaJSON is contracts/market-order-status.schema.json.

var MobilePairingBootstrapCandidateSchemaJSON []byte

MobilePairingBootstrapCandidateSchemaJSON is the Host-owned candidate projection shown to phone and PC clients before a mobile session exists.

var MobilePairingBootstrapRequestSchemaJSON []byte

MobilePairingBootstrapRequestSchemaJSON is the authority-free first-pairing request shape. It intentionally excludes every authority and credential.

var MobileSessionIssueIntentSchemaJSON []byte

MobileSessionIssueIntentSchemaJSON is the body shape for post-approval session issuance. Bootstrap proof stays header-only and is not embedded.

var MonitoringEventSchemaJSON []byte

MonitoringEventSchemaJSON is contracts/monitoring/monitoring-event.schema.json.

var PackExportBundleSchemaJSON []byte

PackExportBundleSchemaJSON is contracts/pack-export-bundle.schema.json.

var PackHandsRequirementReadModelSchemaJSON []byte

PackHandsRequirementReadModelSchemaJSON is the client-safe explanation projection for one Pack Hands requirement. It is not an authority source.

var PackInstallResultSchemaJSON []byte

PackInstallResultSchemaJSON is contracts/pack-install-result.schema.json.

var PackManifestSchemaJSON []byte

PackManifestSchemaJSON is contracts/pack-manifest.schema.json.

var PackUsageContributionCandidateSchemaJSON []byte

PackUsageContributionCandidateSchemaJSON is contracts/pack-usage-contribution-candidate.schema.json.

var PackVersionMigrationCandidateSchemaJSON []byte

PackVersionMigrationCandidateSchemaJSON is contracts/pack-version-migration-candidate.schema.json.

var ProviderRequirementSchemaJSON []byte

ProviderRequirementSchemaJSON is contracts/provider-requirement.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 SceneRuntimePlanCandidateSchemaJSON []byte

SceneRuntimePlanCandidateSchemaJSON is contracts/scene-runtime-plan-candidate.schema.json. It is embedded so the SceneFlow producer can validate the fixed Pack version and provider requirement reference boundary without re-declaring it.

var SoftwareResolutionLockSchemaJSON []byte

SoftwareResolutionLockSchemaJSON is contracts/software-resolution-lock.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"`
}