# Glossary

本页定义 Perago 文档中的固定术语。`避免使用` 表示容易混淆、在 Perago 语境中不宜替代固定术语的说法。

## Task language

### Task Module

一个 Python module，且只声明一个 Perago task worker。

避免使用：app、registry module、multi-task worker file。

### Task Worker

由 typed Python function 和 Perago task metadata 共同定义的一个 Conductor task type。

避免使用：route、endpoint、handler app。

### Task Contract

从 Python 函数签名推导出的输入和输出结构。

避免使用：duplicated params declaration、duplicated output declaration。

### Task Controls

映射到 Conductor TaskDef retry、timeout 和 execution-limit 字段的 Perago 配置对象。

避免使用：task contract、business params、workflow input。

### Task Function Signature

Task worker 必须使用的 Python callable 签名：workspace task 接收 `workspace` 和 `params`，workspace-free task 只接收 `params`，并返回 typed Pydantic model。

避免使用：arbitrary callable、variadic args、keyword-only contract。

## Contract fields

### Workspace Input

Conductor input 中标识 LakeFS repository、writable branch、immutable commit ref 的字段。Perago 会把它暴露成本地路径。

避免使用：business parameter、params field、workspace prefix。

### Workspace Output

Conductor output 中携带成功完成后的 LakeFS repository、writable branch、immutable commit ref 的字段。

避免使用：business result、params field、workspace prefix。

### Params Input

Conductor input 中承载业务 payload 的字段。

避免使用：top-level business fields、workspace metadata。

### Result Output

Conductor output 中承载业务返回值的字段。

避免使用：workspace metadata、top-level business fields。

## Workspace language

### Workspace Prefix

task 在代码里声明的 LakeFS path prefix。Perago 把这个 prefix 暴露成本地 workspace root。

避免使用：workflow input、workflow output、runtime credential。

### Workspace Check

task 声明的本地 workspace 文件检查。源码和公开 API 中仍使用 `guardrail` 命名，例如 `require_file`、`require_glob` 和 `check_guardrails`。

避免使用：business validator、schema validator、data transformer。

### Workspace Access Mode

task 声明的 workspace 意图，用来说明 workspace task worker 是否允许发布 workspace 变更。

避免使用：inferred write mode、runtime guess。

### Read-Only Workspace Task Worker

workspace access mode 禁止 workspace publication 的 workspace task worker。

避免使用：workspace-free task、fake workspace。

### Workspace Path

相对于本地 workspace root 的逻辑路径。

避免使用：absolute path、process working directory path、host-specific storage path。

### Attempt Workspace

一次 task attempt 执行 workspace task worker 时使用的本地文件系统目录。

避免使用：shared worker workspace、task-type workspace、process workspace。

### Workspace Branch

可写 workspace task worker 成功发布时写入的 LakeFS branch。

避免使用：immutable input version、temporary branch。

### Protected Workspace Branch

只接受 Perago 通过 LakeFS merge 更新的 workspace branch。

避免使用：direct object writes、direct branch commit、business lock。

### Workspace Ref

workspace task worker 读取的不可变 LakeFS commit ref。

避免使用：mutable branch name、latest branch head。

## Runtime language

### Task Attempt

Conductor 对一个 task worker 的一次执行 attempt。

避免使用：logical task、worker process。

### Logical Task Key

workflow step 跨重试保持稳定的身份。

避免使用：task id、worker id、process id。

### Workspace Transaction

Perago 管理的发布边界，用于把本地 workspace 结果变成 workspace output。

避免使用：direct branch write、business transaction。

### No-Op Workspace Completion

成功完成但 output workspace ref 与 input workspace ref 相同的 workspace task worker completion。

避免使用：empty commit、fake success。

### Serial Workspace Workflow

所有写入同一个 workspace branch 的 workspace task worker 都按顺序执行，不能并行。

避免使用：parallel workspace writers、fan-out writers。

### Single Active Workspace Workflow

同一时刻只有一个 workflow instance 可以写入某个 workspace branch。

避免使用：duplicate workspace workflow、concurrent rerun。

### Staging Branch

发布前隔离一次 workspace transaction 的短生命周期 LakeFS branch。

避免使用：target branch、workflow branch、permanent branch。

### Attempt Fence

Perago 在发布 workspace transaction 前检查当前 task attempt 是否仍然是 Conductor 的当前 attempt。

避免使用：retry policy、timeout setting。

### Publish Fence

Perago 在发布 workspace transaction 前检查目标 workspace branch 是否仍处于可发布状态。

避免使用：merge strategy、schema validation。

### Publish Budget

Perago 为 LakeFS merge、Conductor completion、heartbeat 和 worker shutdown 预留的操作性时间边界。

避免使用：hard transaction guarantee、exact worst-case duration。

### Workspace Task Worker

接收 versioned workspace 并产出 workspace output 的 task worker。

避免使用：task with optional workspace。

### Workspace-Free Task Worker

只接收 business params 并只返回 business result 的 task worker。

避免使用：empty workspace、fake workspace。

### Worker Process

加载一个 task module 并独立 poll Conductor 的操作系统进程。

避免使用：internal worker slot、process-pool worker。

### Worker ID

运行时给一个 worker process 分配的身份，用于日志和 Conductor polling。

避免使用：task id、process id、logical task key。

### Worker ID Prefix

部署时配置的前缀，worker supervisor 用它生成 worker IDs。

避免使用：worker id、task id、task name。

### Worker Supervisor

`perago start -j` 启动的父进程，负责启动和重启 worker processes。

避免使用：internal task scheduler、shared task pool。

### Module Target

用于定位一个 task module 的 Python import path。

避免使用：file path、object path、module:app target。