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 為：

Input Adapter Contract
Semantic Object Contract
Operator Contract
Workflow Contract
Projection Contract
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$ 至少包含：

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 不得將：

README claim

標記成：

implementation observed

來源 authority 必須顯式。

2.6 Unknown Preservation

無法解析：

X

時應輸出：

status = unresolved

而不是捏造 structure。

三、Semantic Object Contract

3.1 目的

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

基本物件：

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

最小結構：

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

3.4 Edge

最小結構：

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

3.5 Unknown

Unknown 是正式物件：

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

核心原則：

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

3.6 Conflict

衝突不得靜默覆蓋：

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

四、Operator Contract

4.1 目的

Operator 定義：

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

每個 Operator 必須聲明：

operator_id
version
input_types
output_types
required_capabilities
required_context
preserved_invariants
determinism
side_effects
failure_modes
uncertainty_behavior

4.2 Determinism

Operator 可標記：

deterministic
conditionally_deterministic
nondeterministic

LLM Operator 通常至少為：

conditionally_deterministic

4.3 Side Effects

預設：

\text{Operator} = \text{Pure}

除非顯式聲明 effect。

例如：

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 具有：

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 必須聲明：

idempotent = true|false

六、Projection Contract

6.1 目的

將 Semantic Workspace 投影成外部表示：

P_j : W \rightarrow Y_j

6.2 Projection Type

至少區分：

lossless
conditionally_reversible
lossy_summary
generative_projection

6.3 Source Projection

產生 source code 時必須保存：

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

正式狀態：

observed
strongly_inferred
weakly_inferred
claimed
unknown
conflict

7.2 Authority Domain

例如：

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}}

預設應是：

authority = ai_proposal

直到被驗證或批准。

八、Contract Versioning

每個 Contract 使用：

major.minor

Major 改變代表：

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

Minor 改變只能：

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

九、Contract Compatibility

若：

C_A

要求：

semantic-object-1.x

則：

semantic-object-1.2

可相容。

但：

semantic-object-2.0

不可預設相容。

十、結論

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

\boxed{ \text{Stable Contracts} }

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

因此：

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