# PSMR Contract Specification v0.1

**AI-Native Program Semantic Mediation Runtime**  
**文件：** Core Contract Specification  
**版本：** v0.1  
**作者：** Neo.K  
**機構：** EveMissLab  
**日期：** 2026-09-15

**公司：** 一言諾科技有限公司  

---

## 0. 文件目的

本文件定義 PSMR 的六個核心 Contract。其目的不是規定所有未來 Adapter、Operator 與 Projection 的內部實作，而是建立一組穩定的跨模組邊界，使不同來源、不同工具與不同 AI 可以在同一個 Semantic Workspace 中互操作。

六個 Contract 為：

1. Input Adapter Contract
2. Semantic Object Contract
3. Operator Contract
4. Workflow Contract
5. Projection Contract
6. Evidence & Authority Contract

任何新模組只要遵守對應 Contract，即可加入 PSMR，而不必修改其他核心模組。

---

# 一、Contract 的基本形式

所有 Contract 都應明確定義：

$$
C
=
(
I,
O,
P,
K,
F,
E
)
$$

其中：

- $I$：Input requirements；
- $O$：Output guarantees；
- $P$：Preconditions；
- $K$：Preserved invariants；
- $F$：Failure modes；
- $E$：Evidence / provenance obligations。

Contract 的目的不是要求零失敗，而是要求：

$$
\boxed{
\text{Failure must be explicit, typed, and traceable.}
}
$$

---

# 二、Input Adapter Contract

## 2.1 目的

將外部來源：

$$
X_k
$$

轉換為 PSMR 可接受的 Evidence Artifact：

$$
A_k
:
X_k
\rightarrow
E_k
$$

---

## 2.2 Evidence Artifact 最小欄位

每個 $E_k$ 至少包含：

```text
artifact_id
artifact_type
content_identity
source_identity
provenance
authority
permissions
observed_at
uncertainty
payload_ref
```

---

## 2.3 Identity 要求

Adapter 必須區分：

$$
\text{Content Identity}
$$

與：

$$
\text{Source Identity}
$$

例如同一份 source bytes 出現在不同 Git revision：

$$
H(C_1)=H(C_2)
$$

但：

$$
R_1\neq R_2
$$

仍應保留不同 source identity。

---

## 2.4 Provenance Obligation

Adapter 必須能回答：

> 這份資料從哪裡來？

最低形式：

$$
P
=
(
\text{origin},
\text{locator},
\text{version},
\text{method}
)
$$

---

## 2.5 Authority

Adapter 不得將：

```text
README claim
```

標記成：

```text
implementation observed
```

來源 authority 必須顯式。

---

## 2.6 Unknown Preservation

無法解析：

$$
X
$$

時應輸出：

```text
status = unresolved
```

而不是捏造 structure。

---

# 三、Semantic Object Contract

## 3.1 目的

PSMR 中所有語義物件必須使用共同型態。

基本物件：

```text
Artifact
Node
Edge
State
Effect
Contract
Motif
Finding
Unknown
Conflict
HistoryEvent
SemanticDelta
```

---

## 3.2 Semantic Identity

每個物件應具有：

$$
ID_s
$$

表示 semantic identity。

不得預設：

$$
ID_s
=
\text{absolute source location}
$$

source location 是 evidence，不一定是 ontology identity。

---

## 3.3 Node

最小結構：

```json
{
  "id": "...",
  "type": "...",
  "semantic_role": "...",
  "status": "observed|inferred|claimed|unknown",
  "evidence_ids": []
}
```

---

## 3.4 Edge

最小結構：

```json
{
  "id": "...",
  "type": "...",
  "source": "...",
  "target": "...",
  "status": "...",
  "evidence_ids": []
}
```

---

## 3.5 Unknown

Unknown 是正式物件：

```json
{
  "type": "unknown",
  "scope": "...",
  "reason": "...",
  "candidates": [],
  "evidence_ids": []
}
```

核心原則：

$$
\boxed{
\text{Unknown}
\neq
\text{Absent}
}
$$

---

## 3.6 Conflict

衝突不得靜默覆蓋：

```json
{
  "type": "conflict",
  "subject_id": "...",
  "claims": ["..."],
  "resolution": null
}
```

---

# 四、Operator Contract

## 4.1 目的

Operator 定義：

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

每個 Operator 必須聲明：

```text
operator_id
version
input_types
output_types
required_capabilities
required_context
preserved_invariants
determinism
side_effects
failure_modes
uncertainty_behavior
```

---

## 4.2 Determinism

Operator 可標記：

```text
deterministic
conditionally_deterministic
nondeterministic
```

LLM Operator 通常至少為：

```text
conditionally_deterministic
```

---

## 4.3 Side Effects

預設：

$$
\text{Operator}
=
\text{Pure}
$$

除非顯式聲明 effect。

例如：

```text
write_file
run_process
network_request
create_pr
```

必須聲明 capability。

---

## 4.4 Capability

例如：

$$
\operatorname{project\_patch}
$$

可只需要 workspace read。

但：

$$
\operatorname{apply\_patch}
$$

需要：

$$
\operatorname{Cap}_{\mathrm{source-write}}
$$

---

## 4.5 Evidence Output

Operator 的高階結論必須保留：

$$
\text{Conclusion}
\rightarrow
\text{Evidence}
$$

---

# 五、Workflow Contract

## 5.1 Workflow Graph

Workflow：

$$
\Pi
=
(
V_O,
E_O
)
$$

其中 $V_O$ 是 Operator invocation， $E_O$ 是 dependency。

---

## 5.2 Invocation Identity

每次 invocation 具有：

```text
invocation_id
operator_id
operator_version
input_ids
policy_id
capability_set
started_at
completed_at
status
output_ids
```

---

## 5.3 Checkpoint

每個可重用中間結果可以建立：

$$
\text{Checkpoint}
=
H(
O,
I,
P,
C
)
$$

其中：

- $O$：Operator version；
- $I$：inputs；
- $P$：policy；
- $C$：semantic context。

---

## 5.4 Resume

Workflow 必須能從最近合法 checkpoint 繼續。

---

## 5.5 Retry

Retry 不得重複不可逆 effect。

因此 effectful Operator 必須聲明：

```text
idempotent = true|false
```

---

# 六、Projection Contract

## 6.1 目的

將 Semantic Workspace 投影成外部表示：

$$
P_j
:
W
\rightarrow
Y_j
$$

---

## 6.2 Projection Type

至少區分：

```text
lossless
conditionally_reversible
lossy_summary
generative_projection
```

---

## 6.3 Source Projection

產生 source code 時必須保存：

```text
source_language
target_version
semantic_delta_id
projection_policy
validation_requirements
```

---

## 6.4 Round-Trip

若 Projection 宣稱可逆：

$$
W
\xrightarrow{P}
Y
\xrightarrow{\rho}
W'
$$

則必須聲明：

$$
W
\equiv_{\mathcal C}
W'
$$

的驗證條件。

---

# 七、Evidence & Authority Contract

## 7.1 Evidence Status

正式狀態：

```text
observed
strongly_inferred
weakly_inferred
claimed
unknown
conflict
```

---

## 7.2 Authority Domain

例如：

```text
implementation
intent
runtime
schema
human_decision
ai_proposal
external_tool
```

---

## 7.3 Authority 不自動傳遞

例如：

$$
\text{Human Approved Intent}
$$

不代表：

$$
\text{Implementation Observed}
$$

---

## 7.4 AI Proposal

AI 產生：

$$
\Delta W_{\mathrm{AI}}
$$

預設應是：

```text
authority = ai_proposal
```

直到被驗證或批准。

---

# 八、Contract Versioning

每個 Contract 使用：

```text
major.minor
```

Major 改變代表：

- semantic meaning 改變；
- required field 改變；
- compatibility break。

Minor 改變只能：

- 新增 optional field；
- 擴充 enum；
- 增加非破壞性能力。

---

# 九、Contract Compatibility

若：

$$
C_A
$$

要求：

```text
semantic-object-1.x
```

則：

```text
semantic-object-1.2
```

可相容。

但：

```text
semantic-object-2.0
```

不可預設相容。

---

# 十、結論

PSMR 的通用性不是來自支援無限多檔案格式，而是來自：

$$
\boxed{
\text{Stable Contracts}
}
$$

任何新來源、工具、模型或 runtime，只要遵守 Contract，即可進入同一個語義運算世界。

因此：

$$
\boxed{
\text{Extensibility}
=
\text{Contract Compatibility}
}
$$