continuitybinding

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package continuitybinding 实现 user-level continuity binding registry。

binding 把当前 Git repository/worktree 精确映射到一个已注册 vault 和 bounded scope。registry 是 CLI/service 独占写入的 versioned YAML 文件, 存放在 user-level config 目录(owner-only 0600),不进入 repository、 vault note 或 Git。Agent 和用户不得手写该文件。

第一 slice 只支持 exact canonical worktree root 匹配:不按目录名、Git remote、语义相似度或最近使用记录猜测绑定,避免错误合并两个本地 checkout。

Index

Constants

View Source
const (
	// ErrCodeBindingAmbiguous 表示同一 canonical worktree 存在多个 enabled exact binding。
	ErrCodeBindingAmbiguous = "continuity_binding_ambiguous"
	// ErrCodeBindingInvalid 表示 registry 或 binding record 损坏/目标失效。
	ErrCodeBindingInvalid = "continuity_binding_invalid"
)

稳定错误码(additive;不回写已有 agentprotocol 错误码语义)。

View Source
const BindingSchemaVersion = "pinax.continuity_binding.v1"

BindingSchemaVersion 是 continuity binding 的逻辑 schema 版本。

Variables

This section is empty.

Functions

func CanonicalizeRepoRoot

func CanonicalizeRepoRoot(path string) (string, error)

CanonicalizeRepoRoot 把任意 repo 路径规范化为 canonical worktree root。 顺序:Abs → EvalSymlinks。Windows 下大小写不敏感但保留原样, 由 registry 的 exact key 比较负责一致性(测试覆盖)。

注意:这里不做 prefix 匹配。两个路径即使共享前缀也只在完全相等时 命中同一 binding,这是 fail-closed 的关键边界。

func DetectWorktreeRoot

func DetectWorktreeRoot(ctx context.Context, path string) (string, error)

DetectWorktreeRoot 返回 path 所属 Git worktree 的 canonical 顶层目录。

边界说明(中文):

  1. 使用 `git rev-parse --show-toplevel` 解析 worktree 根。该命令在 非 Git 目录返回非零退出码,我们据此返回 not_a_repository 语义; 不向父目录之外的未知位置搜索,也不扫描其他 vault。
  2. 返回路径经 CanonicalizeRepoRoot 规范化(Abs + EvalSymlinks), 使得通过 symlink 进入同一 worktree 的调用命中同一 exact binding key。
  3. 超时 5s 防止损坏的 Git 状态挂起短生命周期 CLI 进程。

func Digest

func Digest(canonicalRoot string) string

Digest 计算 canonical worktree root 的 bounded sha256 digest(16 hex chars)。 digest 用于 machine output 与 receipt 关联,不可逆推出完整路径。

func RedactedRoot

func RedactedRoot(canonicalRoot string) string

RedactedRoot 返回 bounded basename,用于默认 machine output。 只暴露路径最后一段,避免泄漏用户 home 目录结构。

func RegistryPath

func RegistryPath(configDir string) string

RegistryPath 返回 registry 文件路径(user-level config dir 下)。 configDir 为空时使用默认 config dir 调用方提供的路径。

func SaveRegistry

func SaveRegistry(configDir string, registry Registry) error

SaveRegistry 原子写入 registry(temp + rename),权限 owner-only 0600。 原子写保证并发/崩溃时不会留下半截 YAML 触发损坏分支。

Types

type Binding

type Binding struct {
	// BindingID 是 opaque 稳定标识(bind_<digest>)。
	BindingID string `yaml:"binding_id" json:"binding_id"`
	// SchemaVersion 固定为 pinax.continuity_binding.v1。
	SchemaVersion string `yaml:"schema_version" json:"schema_version"`
	// CanonicalRepoRoot 是 canonical(symlink-resolved)worktree 绝对路径。
	CanonicalRepoRoot string `yaml:"canonical_repo_root" json:"-"`
	// RepoRootDigest 是 CanonicalRepoRoot 的 bounded sha256 digest。
	RepoRootDigest string `yaml:"repo_root_digest" json:"repo_root_digest"`
	// VaultRef 是已注册 vault selector(alias 或绝对路径),必须可解析。
	VaultRef string `yaml:"vault_ref" json:"vault_ref"`
	// ScopeKind 是 bounded scope kind(如 project)。
	ScopeKind string `yaml:"scope_kind" json:"scope_kind"`
	// ScopeID 是 bounded scope 标识(如 pinax)。
	ScopeID string `yaml:"scope_id" json:"scope_id"`
	// Enabled 控制该 binding 是否参与自动解析。
	Enabled bool `yaml:"enabled" json:"enabled"`
	// CreatedAt 是创建时间。
	CreatedAt time.Time `yaml:"created_at" json:"created_at"`
	// UpdatedAt 是最近更新时间。
	UpdatedAt time.Time `yaml:"updated_at" json:"updated_at"`
}

Binding 是一条 continuity binding 记录(pinax.continuity_binding.v1)。 canonical_repo_root 只用于本机解析;machine output 只暴露 digest 和 bounded basename,不泄漏完整 home 路径。

func (Binding) Scope

func (b Binding) Scope() agentprotocol.Scope

Scope 返回 binding 的 protocol scope。

func (Binding) Validate

func (b Binding) Validate() error

Validate 检查 binding 记录完整性。 校验失败返回 continuity_binding_invalid,不写任何部分状态。

type BindingStatus

type BindingStatus string

BindingStatus 是 binding 解析状态机,用于 status projection 与自动解析。

const (
	// StatusReady 表示 repository、vault、scope 与 registry 均可解析。
	StatusReady BindingStatus = "ready"
	// StatusMissing 表示当前 worktree 没有 enabled binding。
	StatusMissing BindingStatus = "missing"
	// StatusDisabled 表示 binding 存在但被显式禁用(rollback 保留数据)。
	StatusDisabled BindingStatus = "disabled"
	// StatusInvalid 表示 binding record 或目标 vault/scope 不可解析。
	StatusInvalid BindingStatus = "invalid"
	// StatusAmbiguous 表示同一 worktree 有多个 enabled exact binding(fail closed)。
	StatusAmbiguous BindingStatus = "ambiguous"
	// StatusNotARepository 表示当前目录不属于可解析的 Git worktree。
	StatusNotARepository BindingStatus = "not_a_repository"
)

type Registry

type Registry struct {
	SchemaVersion string    `yaml:"schema_version" json:"schema_version"`
	Bindings      []Binding `yaml:"bindings,omitempty" json:"bindings,omitempty"`
}

Registry 是 continuity binding registry 的 versioned 文件形态。

func LoadRegistry

func LoadRegistry(configDir string) (Registry, error)

LoadRegistry 读取 registry;文件不存在时返回空 registry(不是错误)。 YAML 损坏时返回 continuity_binding_invalid,调用方必须 fail closed。

func (Registry) AnyFor

func (r Registry) AnyFor(canonicalRoot string) []Binding

AnyFor 返回某 canonical root 的全部 binding(含 disabled)。

func (*Registry) Disable

func (r *Registry) Disable(canonicalRoot string, now time.Time) int

Disable 禁用指定 canonical root 的所有 binding(rollback 不删除数据)。

func (Registry) EnabledFor

func (r Registry) EnabledFor(canonicalRoot string) []Binding

EnabledFor 返回某 canonical root 的全部 enabled binding。 多条结果即 ambiguous——registry 写路径保证唯一,读到多条说明状态损坏。

func (*Registry) Upsert

func (r *Registry) Upsert(binding Binding, now time.Time) Binding

Upsert 创建或更新一条 binding。同一 canonical_repo_root 的既有 enabled 记录会被替换(重新绑定同一 worktree 是显式用户操作),不同 root 的 记录保持不变。返回最终写入的记录。

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL