Environment Crystallization

状态：Proposed design。 本文细化 Vinculum 如何把受控观察逐步资格化为 fixture、adapter、state model、oracle 与 versioned cohort。“学习”只指 Harness/adapters/oracles 的受审查工程演化，不允许在线模型自动扩大执行权限。

Canonical system boundary 见 architecture.md；外部 effect 分层见 effects-and-replay.md；当前 Pysolate implementation boundary 见 pysolate-mapping.md。

1. 目标

真实外部环境无法一次性完全建模。Harness 应从受控观察中逐步把不确定依赖转化为：

frozen input；
replay stub；
typed adapter；
state model / digital twin；
independent oracle；
versioned qualification suite。

但必须保持单向安全边界：

text

observation does not grant authority
inference does not become a guarantee
passing examples do not prove a complete model

2. Qualification ladder

text

L0 Unknown
  ↓ record only
L1 Observed surface
  ↓ repeated controlled probes
L2 Inferred contract candidate
  ↓ schema/state model + negative tests
L3 Replay fixture / stub
  ↓ differential validation against live system
L4 Qualified adapter
  ↓ production canary + expiry policy
L5 Stable cohort

任何阶段都可因 drift 退回或 quarantine。各阶段的 artifact、权限变化与退出条件如下：

Stage	主要 artifact	Authority change	Exit condition	Failure action
L0 Unknown	raw observation	无	surface 可重复识别	保持 record-only
L1 Observed	observation corpus	无	已分离 volatile/sensitive fields	回到 L0
L2 Inferred	contract hypothesis	无	schema/state model 通过反例	quarantine candidate
L3 Fixture	frozen stub/model	仅离线 replay	不连接 live provider，结果可验证	禁止 promotion
L4 Qualified	versioned adapter + oracle	Host 可按既有 policy 授权	differential/failure tests 与 expiry 完整	degraded/quarantined
L5 Stable cohort	qualification identity	不新增 authority	在声明 envelope 内持续通过	new cohort 或 requalify

L0 — Unknown

无可靠 schema/effect semantics；
默认禁止写；
记录环境、动作、观察和不确定性。

L1 — Observed surface

形成 selector/endpoint/field 候选；
识别明显 nondeterministic fields；
不把相关性写成因果关系。

L2 — Inferred contract candidate

归纳 request/response schema；
构建 state transition 假设；
设计反例与异常注入；
显式列出 hidden-state hypothesis。

L3 — Replay fixture / stub

canonicalize 并脱敏 recording；
将 time/random/IDs/version 变成显式输入；
为每个 fixture 记录来源版本与 capture policy；
验证 replay 不连接真实 provider、不产生外部写入。

L4 — Qualified adapter

typed schema；
least-privilege credentials；
idempotency/retry/ambiguity contract；
readback oracle；
sandbox/live canary；
expiry/requalification condition。

L5 — Stable cohort

在明确版本和负载包络内持续通过；
历史 replay 绑定旧 cohort；
新版本以新 qualification identity 发布。

3. Crystallization pipeline

3.1 Capture

记录所有影响重放的 nondeterministic inputs：

provider response；
clock/timer；
randomness/UUID；
environment variables 与 locale/timezone；
catalog/schema/policy version；
external state snapshot/reference；
human approval decision；
concurrency/order events。

3.2 Canonicalize

区分：

semantic fields：影响状态转换；
volatile fields：request ID、server time、trace ID；
sensitive fields：credentials、PII、raw prompt；
unresolved fields：无法判断是否影响语义。

只对已证明为非语义的字段做 normalization。不能为了让测试通过而忽略未知差异。

3.3 Model

建立三层模型：

request/response schema；
state transition model；
effect and failure model。

模型应包含 invalid、timeout、duplicate、reordered、partial 和 concurrent cases，而不只 happy path。

3.4 Replay

stub 返回 frozen observation；
simulator 根据状态模型产生 response；
twin 在受控模型中模拟或声明式执行 effects，并暴露可检查状态；其行为不能作为 live provider effect evidence；
replay 记录自己使用的 fixture/model/version digest。

3.5 Differential qualification

对同一 corpus 比较 live provider 与 fixture/twin 的 declared surface：

schema compatibility；
state projection；
effect receipt；
failure classification；
oracle outcome。

差异不应被平均掉；按 semantic / benign-volatile / unknown 分类。差异收敛只支持声明过的 state projection、receipt、failure class 与 oracle outcome，不证明完整语义等价，也不自动授予 provider authority。

3.6 Promotion

只有在以下条件成立后才从 fixture 升级为 qualified adapter：

正反例和 failure injection 通过；
effect class、idempotency 和 ambiguity 语义有依据；
independent readback oracle 成立；
credential scope 与 policy 审查通过；
drift detector 和 quarantine path 可运行；
有明确 expiration。

4. Drift 状态机

text

qualified
  → compatible-change
  → qualified(new cohort)

qualified
  → suspicious-drift
  → degraded(read-only / stub-only)
  → requalifying
  → qualified | quarantined

qualified
  → breaking-or-unknown
  → quarantined

4.1 Drift signals

API/schema/catalog digest 变化；
unknown field 或 enum；
status/error distribution 变化；
idempotency/readback 行为变化；
DOM/selector/visual fingerprint 变化；
state-transition differential failure；
latency/rate-limit 跨出 qualification envelope；
oracle 与 provider acknowledgement 冲突；
model/provider silent version update。

4.2 响应级别

状态	允许能力
`qualified`	按 policy 正常运行
`degraded`	read-only、record、stub replay；暂停高风险写
`quarantined`	禁止 live adapter；保留历史 verifier/replayer
`unsupported`	无可靠适配路径，只 record/document

4.3 版本演化

Temporal 的经验说明：历史 replay 对 workflow code 变化敏感，外部交互应隔离为 nondeterministic activities，并需要 versioning/replay test。对应到本设计：

历史 Evidence Bundle 绑定原 execution/replayer/adapter cohort；
新代码不能“兼容读取成功”就冒充历史 replay 等价；
迁移必须有 old-history corpus；
old cohort 可只读保留用于验证，不必继续承载新执行；
无法解释的 replay divergence 应 fail-closed。

5. Harness extension interface

Proposed illustrative interface; not a current Pysolate API. 这些方法由 Host-side Harness/adapter implementation 持有；generated program 只看见 Frozen Capability Surface 中已经授权的 typed call surface。rollback 仅适用于 reversible，compensate 仅适用于 compensatable。

text

EnvironmentAdapter
├── discover()          # 只读 surface/版本发现
├── snapshot()          # 取得受支持的状态投影
├── classify_effect()   # 基于资格化规则，不由 LLM 决定
├── stage()             # 构建 immutable intent
├── apply()             # 派发一次 attempt
├── reconcile()         # 解决 ambiguous outcome
├── rollback()          # 仅 reversible
├── compensate()        # 仅 compensatable
├── verify()            # independent state oracle
├── record_fixture()    # 脱敏、版本化
└── drift_probe()       # 无副作用或 disposable canary

每个方法返回 typed evidence，而不是 free-form success string。

6. 学习系统的安全边界

6.1 禁止自动扩大权限

recorder 可以建议 adapter candidate；
model 可以提出 schema/state hypothesis；
但 tool exposure、credential scope、effect class、commit policy 和 promotion 由 Host qualification 决定。

6.2 数据污染与 prompt injection

外部页面、tool response 和 recording 都是不可信输入：

不执行其中的指令；
provenance 记录数据来源；
训练/归纳 corpus 分 tenant 与信任等级；
promotion tests 包含 adversarial content；
raw capture 与 portable evidence 分离。

6.3 隐私

默认 digest/metadata-first；
raw fixture 需独立访问控制和 retention；
canonicalization 必须防止 token、cookie、PII、prompt 泄漏；
“为了可重放”不能成为无限保留用户内容的理由。

7. 评价方法

持续学习的目标不是 adapter 数量，而是：

未知环境被正确拒绝或降级的比例；
qualification 后的 live/fixture semantic divergence；
drift detection latency；
false quarantine / missed drift；
ambiguous effect 的正确 reconciliation；
replay fidelity 相对于声明级别；
新 cohort 资格化成本；
raw data retention 与 privacy exposure；
攻击性内容能否影响 policy/promotion。

8. 最小 promotion sequence

实施切片与验收由 pysolate-mapping.md 统一维护。Environment Crystallization 只规定 promotion 顺序：

text

controlled fixture
  → known API with idempotency/readback
  → unknown read-only surface
  → frozen replay fixture
  → read-only qualified adapter
  → injected drift and quarantine test
  → low-risk compensatable write, if separately authorized

任何阶段未通过 expiry、drift 或 evidence gate，都不得进入下一阶段；通过观察学习到的新字段或动作也不得自动扩大 authority。

Environment Crystallization ​

1. 目标 ​

2. Qualification ladder ​

L0 — Unknown ​

L1 — Observed surface ​

L2 — Inferred contract candidate ​

L3 — Replay fixture / stub ​

L4 — Qualified adapter ​

L5 — Stable cohort ​

3. Crystallization pipeline ​

3.1 Capture ​

3.2 Canonicalize ​

3.3 Model ​

3.4 Replay ​

3.5 Differential qualification ​

3.6 Promotion ​

4. Drift 状态机 ​

4.1 Drift signals ​

4.2 响应级别 ​

4.3 版本演化 ​

5. Harness extension interface ​

6. 学习系统的安全边界 ​

6.1 禁止自动扩大权限 ​

6.2 数据污染与 prompt injection ​

6.3 隐私 ​

7. 评价方法 ​

8. 最小 promotion sequence ​

Environment Crystallization

1. 目标

2. Qualification ladder

L0 — Unknown

L1 — Observed surface

L2 — Inferred contract candidate

L3 — Replay fixture / stub

L4 — Qualified adapter

L5 — Stable cohort

3. Crystallization pipeline

3.1 Capture

3.2 Canonicalize

3.3 Model

3.4 Replay

3.5 Differential qualification

3.6 Promotion

4. Drift 状态机

4.1 Drift signals

4.2 响应级别

4.3 版本演化

5. Harness extension interface

6. 学习系统的安全边界

6.1 禁止自动扩大权限

6.2 数据污染与 prompt injection

6.3 隐私

7. 评价方法

8. 最小 promotion sequence