# PSMR Semantic Workspace Schema v0.1

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

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

---

## 0. 目的

本文件定義 PSMR Semantic Workspace：

$$
W
=
(
A,
G,
K,
H,
U,
C
)
$$

的第一版工程 Schema。

Semantic Workspace 是 AI、人類與工具共同操作的軟體語義世界，不等同於檔案系統，也不等同於單一 Graph。

---

# 一、Workspace Root

```json
{
  "schema": "psmr-workspace-0.1",
  "workspace_id": "...",
  "created_at": "...",
  "updated_at": "...",
  "artifacts": [],
  "graphs": [],
  "contracts": [],
  "history": [],
  "unknowns": [],
  "conflicts": [],
  "capabilities": [],
  "workflow_runs": [],
  "projections": []
}
```

---

# 二、Artifact

Artifact 是外部或內部工件。

```json
{
  "artifact_id": "art_...",
  "artifact_type": "source_file",
  "content_hash": "sha256:...",
  "source_identity": {
    "origin": "git",
    "repository": "...",
    "revision": "...",
    "path": "..."
  },
  "authority": "implementation",
  "status": "observed",
  "payload_ref": "..."
}
```

---

# 三、Graph Registry

Workspace 可以同時存在多張 graph：

```json
{
  "graph_id": "graph_...",
  "graph_type": "cisg",
  "schema": "pbsio-cisg-1.0",
  "source_artifact_ids": [],
  "node_count": 0,
  "edge_count": 0,
  "payload_ref": "..."
}
```

Graph type 可以包含：

```text
cisg
dataflow
state
effect
motif
runtime
intent
dependency
workflow
```

---

# 四、Contract Object

```json
{
  "contract_id": "contract_...",
  "contract_type": "postcondition",
  "subject_ids": ["..."],
  "expression": "...",
  "authority": "intent",
  "status": "claimed",
  "evidence_ids": []
}
```

---

# 五、Unknown Object

Unknown 必須有 stable identity。

```json
{
  "unknown_id": "unknown_...",
  "subject_ids": ["..."],
  "kind": "unresolved_call_target",
  "reason": "...",
  "candidate_ids": [],
  "status": "unknown",
  "evidence_ids": []
}
```

---

# 六、Conflict Object

```json
{
  "conflict_id": "conflict_...",
  "subject_id": "...",
  "claim_ids": ["..."],
  "resolution": null,
  "status": "open"
}
```

---

# 七、History Event

```json
{
  "event_id": "event_...",
  "event_type": "semantic_diff",
  "timestamp": "...",
  "before_ids": [],
  "after_ids": [],
  "delta_id": "...",
  "evidence_ids": []
}
```

---

# 八、Semantic Delta

修改不應只表示 patch。

定義：

$$
\Delta W
=
(
\Delta A,
\Delta G,
\Delta K,
\Delta H,
\Delta U
)
$$

Schema：

```json
{
  "delta_id": "delta_...",
  "base_workspace_id": "...",
  "operations": [
    {
      "op": "add_edge",
      "graph_id": "...",
      "payload": {}
    }
  ],
  "intent_ref": "...",
  "status": "proposed",
  "authority": "ai_proposal"
}
```

---

# 九、Capability

```json
{
  "capability_id": "cap_...",
  "name": "source-write",
  "scope": ["repo/path/**"],
  "granted_to": ["workflow:..."],
  "expires_at": null
}
```

---

# 十、Workflow Run

```json
{
  "run_id": "run_...",
  "workflow_id": "...",
  "status": "completed",
  "invocation_ids": [],
  "input_artifact_ids": [],
  "output_artifact_ids": []
}
```

---

# 十一、Projection Record

```json
{
  "projection_id": "proj_...",
  "projection_type": "source_patch",
  "source_workspace_id": "...",
  "semantic_delta_id": "...",
  "target": {
    "language": "python"
  },
  "payload_ref": "...",
  "validation_status": "pending"
}
```

---

# 十二、Identity Layers

PSMR 必須區分：

$$
ID_{\mathrm{artifact}}
$$

$$
ID_{\mathrm{semantic}}
$$

$$
ID_{\mathrm{evidence}}
$$

$$
ID_{\mathrm{workflow}}
$$

不得假設：

$$
ID_{\mathrm{artifact}}
=
ID_{\mathrm{semantic}}
$$

---

# 十三、Workspace Slice

AI 不需要每次取得全部 $W$。

定義：

$$
S
=
\operatorname{Slice}(W,Q)
$$

其中 $Q$ 可以是：

- node；
- motif；
- contract；
- file；
- intent；
- finding。

Slice 必須包含：

```text
selected objects
required neighborhood
contracts
unknowns
conflicts
evidence references
```

---

# 十四、Workspace Update

Operator 不應直接原地靜默修改 Workspace。

應產生：

$$
(W,\Delta)
\rightarrow
W'
$$

並保留：

```text
delta_id
operator invocation
before identity
after identity
```

---

# 十五、Canonical Serialization

對需要 cache / identity 的 Workspace subset，必須提供 canonical serialization：

$$
N(W)
$$

並計算：

$$
ID(W)
=
H(N(W))
$$

---

# 十六、Workspace 與 PBSOI CISG

PBSOI CISG v1.0 在 Workspace 中是：

```text
Artifact(s)
→ CISG Graph
→ Data/State Graph
→ Findings
→ Motifs
→ Semantic Diffs
→ Review Fingerprints
```

它不是 Workspace 本身。

---

# 十七、結論

Semantic Workspace 是 PSMR 的中央狀態。

其核心不是檔案，而是：

$$
\boxed{
\text{Artifacts}
+
\text{Graphs}
+
\text{Contracts}
+
\text{History}
+
\text{Unknown}
+
\text{Authority}
}
$$

AI 應操作 $W$，而不是反覆直接操作整個 Repository。