# PSMR Operator Protocol v0.1

**版本：** v0.1  
**日期：** 2026-09-15

**作者：** Neo.K  
**機構：** EveMissLab／一言諾科技有限公司  

---

## 0. 目的

本文件定義 PSMR Operator 的調用協定。

Operator 是 PSMR 的基本運算單位：

$$
O_i
:
W
\rightarrow
(W',\Delta,E)
$$

---

# 一、Operator Manifest

每個 Operator 必須發布 manifest：

```json
{
  "operator_id": "pbsio.semantic_diff",
  "version": "1.0.0",
  "input_types": ["graph:cisg"],
  "output_types": ["semantic_delta"],
  "required_capabilities": [],
  "side_effects": [],
  "determinism": "deterministic",
  "cacheable": true
}
```

---

# 二、Invocation Request

```json
{
  "invocation_id": "inv_...",
  "operator_id": "pbsio.impact",
  "operator_version": "1.0.0",
  "workspace_id": "...",
  "input_refs": ["..."],
  "parameters": {
    "depth": 3
  },
  "policy_ref": "...",
  "capability_refs": []
}
```

---

# 三、Invocation Result

```json
{
  "invocation_id": "inv_...",
  "status": "completed",
  "output_refs": ["..."],
  "semantic_delta_ref": null,
  "evidence_refs": [],
  "unknown_refs": [],
  "conflict_refs": [],
  "metrics": {},
  "error": null
}
```

---

# 四、Status

正式狀態：

```text
pending
running
completed
completed_with_unknowns
blocked
failed
cancelled
```

---

# 五、Failure

Failure 必須 typed：

```json
{
  "code": "CAPABILITY_DENIED",
  "message": "...",
  "retryable": false,
  "details": {}
}
```

---

# 六、Pure Operator

Pure Operator：

$$
O(W)
=
Y
$$

不得修改外部世界。

例如：

```text
query_subgraph
impact
semantic_diff
detect_defects
match_motif
```

---

# 七、Effectful Operator

例如：

```text
apply_patch
run_tests
create_pull_request
deploy
```

必須聲明：

```text
side_effects
required_capabilities
idempotence
rollback support
```

---

# 八、Capability Check

調用前：

$$
C_{\mathrm{required}}
\subseteq
C_{\mathrm{granted}}
$$

否則：

```text
CAPABILITY_DENIED
```

---

# 九、Cache Key

可 cache Operator 定義：

$$
K_O
=
H(
O_{\mathrm{id}},
O_{\mathrm{version}},
I,
P,
C
)
$$

其中 $C$ 只包含會影響結果的 semantic context。

---

# 十、Deterministic Operator

若：

```text
determinism = deterministic
```

則相同 $K_O$ 必須產生相同 canonical result。

---

# 十一、AI Operator

LLM Operator 必須額外聲明：

```text
model
model_version
prompt_contract
temperature
tool_set
```

其輸出預設 authority：

```text
ai_proposal
```

不能直接等同 verified fact。

---

# 十二、Operator Chaining

若：

$$
O_A
:
X\rightarrow Y
$$

且：

$$
O_B
:
Y\rightarrow Z
$$

則可：

$$
O_B\circ O_A
$$

但只有在 type contract 相容時成立。

---

# 十三、PBSOI v1.0 Operator Mapping

現有能力可映射為：

```text
pbsio.observe_source
pbsio.build_cisg
pbsio.semantic_diff
pbsio.impact
pbsio.detect_defects
pbsio.match_motifs
pbsio.incremental_recompute
pbsio.rebase_evidence
```

---

# 十四、AI-Facing Query Operators

建議第一批公開：

```text
query_subgraph
get_evidence
get_findings
impact
semantic_diff
find_motif
get_state_region
get_boundary
```

---

# 十五、Modification Operators

未來加入：

```text
propose_semantic_delta
validate_semantic_delta
project_delta_to_source
apply_projection
reconstruct_workspace
verify_roundtrip
```

---

# 十六、Operator Evidence

Operator 必須能提供：

```text
which inputs were used
which rules were applied
which output facts were generated
which unknowns remain
```

---

# 十七、Streaming

大型 Operator 可串流：

```text
progress
partial_output
evidence
warning
```

但 partial result 必須標記：

```text
status = partial
```

---

# 十八、Cancellation

Workflow Runtime 可以發送 cancellation。

Effectful Operator 必須聲明是否可安全取消。

---

# 十九、Operator Sandbox

外部 Operator 不應自動取得 Workspace 全權。

應只獲得：

$$
\operatorname{Slice}(W)
$$

與必要 capability。

---

# 二十、結論

Operator Protocol 的目的，是把「AI 幫我做某件事」轉成：

$$
\boxed{
\text{Typed Semantic Operation}
}
$$

如此才能使 AI、deterministic tool、human step 與外部服務存在於同一工作流中。