行内元素#

普通段落。加粗、斜体、行内代码、站内链接、外部链接（外部链接会自动加 rel="noopener" 并在新标签打开）。

引用块用衬线斜体，左侧一根朱砂竖线。

适合放定义、结论，或者从别处摘来的原话。第二段会和第一段保持一点间距。

列表#

无序列表：

• 第一项，短一点
• 第二项，稍微写长一些，用来观察换行后的行距是否还舒服
• 第三项
  • 嵌套一层，缩进由 padding-left 控制
  • 再一条

有序列表：

1. 先确认目标
2. 再拆步骤
3. 最后验证结果——做完不等于做对，验证要单独算一步

代码#

行内的 ss -lntp 长这样。块级代码带语言标签和复制按钮，语言名写在围栏后面：

from pathlib import Path

def files_under(root: Path) -> int:
    """统计目录下的文件数。"""
    return sum(1 for p in root.rglob("*") if p.is_file())

print(files_under(Path("dist")))

# 查看 nginx 实际监听的端口与进程
ss -lntp | grep -E ":80 |:443 "

# 语法检查后平滑重载
nginx -t && nginx -s reload

没有标语言的代码块会按纯文本渲染：

这是一段没有语言标记的文本块
    保留了缩进

表格#

图片#

图片放在 static/img/ 下，用绝对路径引用，构建时会一起同步：

![说明文字](/assets/img/example.png)

分割线与结尾#

分割线在正文里是一根居中的短横，用来做场景切换。

写到这里，元素基本齐了。以后加新语法（脚注、数学公式之类），先在这里补一条，再拿去正式文章里用。

DeepSeek Harness（dsh） 是 DeepSeek AI 官方开源的 agent harness（智能体运行时框架），MIT 协议，当前 0.1.0-rc.5（开发者预览，快速迭代，官方声明有破坏性变更）。

与"一个 agent 应用"的区别：它是承载 agent 的框架 —— 你可以用它运行自己的 agent（Web UI / headless / ACP），也可以把 Claude Code、Codex 桥接进来当执行后端。架构核心是一切皆插件，底层由 Cordis 插件框架驱动（vendored，@deepseek-ai/cordis v4.0.1），设计源自论文《A Programming Paradigm for Spatiotemporal Composability》。

• CLI: dsh web（Web UI @ 127.0.0.1:3080）/ dsh --profile headless "task"（一次性 runner）
• npm: npx @deepseek-ai/dsh web
• Tech stack: TypeScript monorepo（pnpm，Node ^22.19 || >=24），~2085 个 TS 源文件，49 个包组、~130+ 工作区包
• Python SDK: python/sdk（JSON-RPC stdio 客户端）
• Home: https://github.com/deepseek-ai/deepseek-harness

Core Architecture#

1. 一切皆插件（Cordis）#

没有特权核心：模型适配器、工具注册表、会话日志、甚至 agent loop 本身都是插件，全部可从配置替换（见 Plugin-Everything Architecture）。

• Context 是服务仓库：服务占用稳定 ctx.<key>（ctx.tools / ctx.llm / ctx.sessions），插件通过 key 找服务而非 import 具体实现
• inject 声明依赖：加载顺序由服务依赖表达
• 可逆副作用：注册都通过 ctx.effect() / ctx.on()，插件卸载时自动回滚
• 四种事件派发：emit（观察）/ waterfall（中间件链，需调 next()）/ parallel（并行）/ serial（按序）

2. Capability Seam（能力接缝）#

每个可替换能力拆成三角色：Service Definition（接口）/ Service Provider（实现）/ Consumer（模型工具）。换 provider（本地 bash → 远程沙箱 → pwsh）不影响模型可见契约（见 Capability Seam）。

核心接缝：llm、shell、fs、subprocess、terminal、web、lsp、skill、subagent、sandbox、compaction、code-runtime、jobs、approval。

3. 事件溯源会话日志#

Session 是 append-only 的 SessionEvent 日志 —— 单一事实来源。LLM 消息历史从日志派生（deriveMessages()），不单独存储。"模型可见 ⇒ 已记录"是运行时不变式（见 Event-Sourced Session Log）。

4. Turn/Step 循环#

turn = 0+ 个 step；step = 一次模型请求 + 其调用的工具。完整流水线见 Agent Turn-Step Loop。

Key Subsystems#

Engineering Culture#

• 1372 个 Agent Notes（.agents/notes/，implemented/proposed/rejected/archived 四态）—— 用 agent 开发 agent 的工程文化，每个架构决策可检索
• 双语文档体系（.md + .zh.md + .i18n.yaml 配对），生成式目录（config-catalog / tool-catalog / module-graph / capability-seams 图）
• 严格规则：非平凡变更必须带 Agent Note；同进程 typed 边界不重复运行时校验；switch on discriminant tags；waterfall 必须调 next()

Cordis 是 DeepSeek Harness 底层的插件框架：插件向共享 context 贡献服务、类型化事件和可逆副作用。设计源自论文《A Programming Paradigm for Spatiotemporal Composability》（cordiverse/paper）。

DeepSeek Harness 没有依赖 npm 版 Cordis，而是vendored 进仓库（vendor/cordis），并全部 rescope 为 @deepseek-ai/*（@deepseek-ai/cordis v4.0.1，上游 cordis 4.0.0-rc.7 快照）—— 完全拥有框架层：可审计、可打补丁、可随 harness 发布。

• 上游: https://github.com/cordiverse/cordis
• Vendored 版本: 4.0.1（本地修改 17+ 项）
• 配套库: cosmokit 1.8.1、schemastery 3.18.0（schema 校验）、loader/include/group/timer/hmr/logger-console 插件

Core Ideas（五要素）#

1. 插件是实现 Service 的对象：函数（可选 inject + apply(ctx)）或 Service 子类，生命周期由 Cordis 挂载到当前 context
2. Context 是服务仓库：服务占用稳定 ctx.<key>（ctx.tools、ctx.llm、ctx.sessions），插件通过 key 找服务而非 import 具体实现
3. inject 声明依赖：插件声明所需服务，等服务存在后再加载 —— 加载顺序由服务依赖表达而非手动排布
4. 类型化事件通信：服务通过 TypeScript declaration merging 声明事件名，然后按 emit / waterfall / parallel / serial 派发
5. 注册是可逆副作用：prompt 分段、工具 schema、适配器、监听器都通过 ctx.effect() / ctx.on() 安装，reload/teardown 可预测回滚

Dispatch Modes#

Waterfall 语义：监听器 (...args, next)，调 next() 委托（可能包装的结果传给下一个），不调则短路。策略监听器短路是设计（拥有决策），注解/观察监听器必须委托。

Vendoring 决策（DeepSeek Harness 特有）#

• 9 个包全量源码拷贝进 vendor/：cosmokit、schemastery、cordis、loader、include、group、timer、hmr、logger-console
• 全部 rescope 为 @deepseek-ai/*（发布 harness 即发布框架层；占用上游名会 squat registry）
• 目录名和上游版本号故意不变，manifest 仍可读为上游快照；linkWorkspacePackages 让保留的 semver 范围解析到 pin 的 workspace
• 17+ 项本地修改日志（vendor/README.md）：fiber 生命周期硬化（3 处 reentrant disposal 缺口）、事务性 Loader/Include 配置协调、HMR 精确配置监听（Windows 路径）、!!js 表达式惰性求值（loader config）、include patch 语义导出等

Extension Points（dsh 内用法）#

• ctx.effect() / ctx.on() 安装可逆副作用
• Map → derived-union 模式：插件通过 declare module 声明合并扩展 ContentBlockMap、SessionEventMap、TurnTriggerMap、FinishReasonMap 等 6 个 canonical maps —— 无需改拥有包
• isolate realm：preset 挂载的服务对 host 不可见（agent preset 组合的基础）

"一切皆插件"（plugin-everything） 是 DeepSeek Harness 的架构主张：没有特权核心。模型适配器、工具注册表、会话日志、甚至 agent loop 本身都是插件，全部可从配置替换。你扩展 dsh 的方式 = 在别的插件旁边挂一个插件。

底层框架是 Cordis（vendored）。

核心机制#

1. Context = 服务仓库#

服务占用稳定 ctx.<key>（ctx.tools、ctx.llm、ctx.sessions）。插件通过 key 找服务，不 import 具体实现 —— 运行时组合而非编译时耦合。

2. inject 声明依赖#

插件 inject: ['shell'] 声明所需服务，等服务存在后再加载。加载顺序由服务依赖表达，而非手动 boot 排布。

3. 可逆副作用（Registrations are effects）#

每个贡献（prompt 分段、工具 schema、适配器、监听器、provider）都通过 ctx.effect() / ctx.on() 安装；注册返回 disposer。插件卸载时一切可预测回滚 —— 没有"卸载残留"。

4. 声明合并扩展（Map → derived-union）#

几乎所有可扩展 sum type 遵循一个模式：interface 按 discriminant tag 建 map（ThingMap），union 用 keyof 派生。插件通过 declare module 声明合并添加变体 —— 无需改拥有包：

// 插件扩展，不改 dsh-session 源码
declare module '@deepseek-ai/dsh-session' {
  interface SessionEventMap {
    'compaction/summary': { /* ... */ }
  }
}

6 个 canonical maps：ContentBlockMap、MessageSourceMap、FinishReasonMap、TurnTriggerMap、TurnEndReasonMap、SessionEventMap。

5. 四种事件派发#

emit（观察）/ waterfall（中间件链，需 next()）/ parallel（并行）/ serial（按序）—— 见 Cordis。

组合机制：Profile / Bundle / Patch#

• Profile：命名组合（Harness home 内），列出 bundle + 用户 cordis.patch.yml；web / headless 是模板
• Bundle：Cordis config rows + 其代码的分发格式（dsh.profile 列 bundle，dsh.bundle 指向 patch 文件）
• Patch 层序：profile bundles（按列序）→ profile patch → home-level patch → --patch overlay。patch 按 row id 替换整个 config 或插入新 row
• dsh-base = 每个 profile 第一层（模型适配器、工具、持久化、sandbox/approval 政策、settings/credentials/telemetry）
• 验证：dsh --profile web --dump-config 打印实际启动的插件树；每行都可被你的 patch 替换

能力作用域：Scope 与 Agent Preset#

• Scope（作用域）：per-agent 注册原语（createScope/scopeOf/scopeTarget），session/agent 的注册是 agent-local，disposal 时回滚
• Agent Preset（ctx.agentPresets）：per-session agent 组合，从 preset cordis.yml 在 agent scope 下挂载
  • 子 agent 通过 composeFrom 继承父的组合（bind 非 mount —— 拿到父的同一 generation，保证与父历史一致）
  • isolate realm：preset 挂载的服务对 host 不可见（agent 私有服务）
  • recompose 可在 agent 无产出时换 preset（有产出则禁止 —— 已记录的工具调用新组合做不了）

Why（价值）#

1. 可组合：产品是插件树，任何层可被更高层 patch 覆盖
2. 可热改：HMR 支持运行时配置/模块热更新
3. 可替换：换 provider、换 loop、换持久化后端，全部从配置
4. 可回滚：副作用可逆，卸载无残留
5. 可扩展无 fork：声明合并扩展 map，不改拥有包源码

Trade-offs / Open Questions#

• "一切皆插件"的代价：心智模型复杂、调试插件树困难（有 --dump-config 缓解）
• 插件粒度：dsh 拆成 ~130+ 工作区包，包爆炸是真实成本（capability seam 规则部分缓解）
• 框架层 vendoring（cordis 17+ 本地修改）：拥有框架层 = 可审计可补丁，但同步上游成本高

Capability Seam（能力接缝） 是 DeepSeek Harness 中"可替换能力"的模块化模式：一个可替换能力拆成三个角色，分别放在独立包中：

1. Service Definition — Cordis Service + vocabulary types，拥有 ctx.<key>，只依赖契约所需词汇。它是一个 Service（抽象类或具体注册表服务），绝不是 TS interface
2. Service Provider — 提供/注册实现的插件（如 dsh-bash-local、dsh-bash-sandbox）
3. Consumer — 模型和插件编程对向（如 dsh-tool-bash：bash 工具 schema）

三者中任何一个角色都不构成 seam。一个完整的接缝 = Service Definition + 一个或多个 Provider + 一个或多个 Consumer。

Why#

可替换能力的三个关注点以不同速率、因不同原因变化：

• 契约（能力是什么）—— 极少变
• 实现（怎么跑）—— 常变（本地 → 沙箱 → 远程）
• 消费者 API（模型/插件对向）—— 变但独立

如果合并一个包，换本地 executor 为沙箱 executor 会牵连模型看到的工具 schema，即使模型契约从未变。拆分后：Service Provider 和 Consumer 独立演进，新后端永不冒模型契约风险。

这不同于"运行时谁提供/谁需要能力"（Cordis services + inject 已解决），seam 决定的是包边界。

Canonical Example（bash 三件套）#

换执行器（本地 bash → landlock 沙箱 → Windows pwsh）不影响模型怎么请求 bash。

Variants（何时不分拆）#

• LLM seam 折叠了 Definition 和 Consumer：Consumer 是 loop 本身（不是可替换的 schema 表面），适配器作为 Provider 包（llm-deepseek / llm-pi-ai / llm-replay）
• subagent 是"多 provider 并存"变体：ctx.subagents 按名注册多个 provider（in-process / acp / codex / claude-code / dsh-sdk），不同于 bash 的单执行器 —— 其注册表跟随 LLM adapter registry 模式
• web 是一个接缝两个操作（search + fetch）：一个 provider-selection 政策所有者、一个 abort/error 词汇，但 Provider 分 WebSearchProvider / WebFetchProvider 注册能力（非工具）

Full Seam Inventory（dsh）#

ctx.llm、ctx.shell、ctx.subprocess、ctx.fs、ctx.terminal、ctx.web、ctx.lsp、ctx.skills、ctx.subagents、ctx.sandbox、ctx.compaction、ctx.codeRuntime、ctx.jobs、ctx.approval、ctx.sessionPersistence、ctx.settings、ctx.credentials、ctx.sessionTelemetry、ctx.storage、ctx.sessionQuery、ctx.sessionTitle、ctx.userQuestions、ctx.directoryPicker、ctx.workflowEngine、ctx.spillStore、ctx.attachments

Trade-offs#

• 代价：拆分增加包和样板（package.json、tsconfig、README、injection wiring）
• 收益：Provider 和 Consumer 独立发布/版本化；新后端零风险触碰模型契约
• 不预拆分：一个能力只有一个想象 provider 和一个 Consumer 时保持单包，直到第二个出现

Turn-Step 循环 是 DeepSeek Harness agent 驱动（agent-loop）的核心执行模型：

• step（步骤） = 一次模型请求 + 它调用的工具
• turn（回合） = 0+ 个 step：在第一个输入被认领前打开，一旦没有欠账就关闭

一个 agent 交互被建模为嵌套的 turn → step → 工具执行，每一层都有 durable session event（见 Event-Sourced Session Log）。

Turn Flow（完整流水线）#

turn/start
  claim next-step input + 1 queued next-turn message
  assemble prompt sections + tool schemas（ctx.systemPrompt）
  -> agent/pre-step                [waterfall] reject | enter(messages)
     reject / 空 enter → turn 无 step 关闭
     step/start
     append user/message
     deriveMessages → agent/request [waterfall] → llm/stream
       → assistant/chunk* → assistant/message
     tool/call* → tools/pre-execute → tools/execute → tools/post-execute → tool/result*
     step/end
     工具还欠请求，或 next-step 输入到达 → claim → 下一 step
  -> agent/turn-stopping           [serial]
turn/end

事件分三类：

• Durable session events：turn/*、step/*、user/message、assistant/*、tool/* —— 持久化事实
• Live agent events（agent/*）：created、disposed、status、inbox/*、pre-step、request、request-error、session-start、turn-stopping —— 观察/拦截在飞工作
• Capability events（fs/*、tools/*、telemetry/*）：给 seam 挂政策和适配器

Agent Handle#

Agent 是每个插件（UI、hooks、orchestrators）编程对向的接口：

• send(message, target, wakeup) — 路由到 inbox 边界（next-turn / next-step）
• followup() — 排队普通后续回合并唤醒
• steer() — 最近 step 的转向输入（运行中在下一步边界消费）
• inject() — 排队模型面向上下文，不唤醒（下一 pre-step 认领）
• cancel(cause, options) — 清队列 + abort 活跃 turn；cause: user | parent | hook | disposed
• whenIdle() — 整个 agent 活动达到静止
• runMaintenance() — turn 间维护任务（compaction 用）
• Status: idle | running

Inbox = 两个有序 pending 队列（next-turn / next-step），agent 拥有作为 durable 投影；claim() 移除 proposed step batch（所有 next-step + turn 边界时 1 个 next-turn）。

关键机制#

agent/pre-step（waterfall）#

唯一在请求派生前的 serial listener chain。监听器可以 reject（不开 step）或 enter（替换进入 step 的消息批次）。被 reject 的消息不丢弃也不重发，turn 无 step 关闭并记录尝试。PreStepDecision = { kind: 'reject' } | { kind: 'enter'; messages }。

agent/request（waterfall）#

替换冻结的 call config。await next() 得到机器将用的 config（首次请求用 agent options，之后用 logged header）；可返回替换。不能改消息 —— 模型可见内容必须走 logged channels。

工具调度（executeToolCalls）#

• exclusive 调用形成屏障（单独跑）；parallel 调用滚动池并行（isConcurrencySafe 决定）
• 结果按模型顺序提交；abort 为未启动调用记录合成 error result 保持 replay 有效
• deferContext() 给复合工具嵌套派发上下文；concludeTurn() 标记终端结果（提前结束 turn）
• Code Mode：run_code 子调度经 tools/code-dispatch-log waterfall

max-tokens sticky#

一旦某 step 达 max-tokens 上限，后续正常完成的 step 不得降级 turn 结局。

错误恢复#

agent/request-error（waterfall）：failed model step 关闭后、turn 关闭前运行；监听器可返回 { kind: 'retry' }（拥有恢复）或 delegate（默认 terminal）。

设计要点#

• 输入经一个 inbox：某些消息立即唤醒驱动；injected context 在 inbox 等另一消息唤醒
• turn/end 在无 step 时也记录（reject / empty / cancelled / failure）—— 尝试本身可审计
• 扩展插件依赖 agent（含需要 initiator 时），不依赖 agent-loop —— loop 保持可替换

事件溯源会话日志 是 DeepSeek Harness 会话的核心架构：Session 是 append-only 的 SessionEvent 日志 —— 一个 agent 完整交互历史的单一事实来源。LLM 消息历史从日志派生（deriveMessages()），不单独存储；重放就是重新派生。

核心不变式："模型可见 ⇒ 已记录"（Model-visible ⟺ logged）。任何到达模型请求的内容必须能从日志重构 —— 新的模型可见输入必须新增 session event 类型。

SessionEventMap（事件词汇）#

merge-extensible：插件通过 TypeScript declaration merging 扩展事件类型（如 compaction 插件添加 compaction/start/summary/end）。

Core 事件：

SessionEvent 结构#

• proper discriminated union over type：switch (event.type) 窄化 event.data，无需 cast
• seq = log.length 单调连续；事件不可变 deep-frozen
• Session.append() 在 append 时校验 JSON 可序列化（BigInt/function/Map/Date 等拒绝）和 surface 契约 —— 坏事件在源头失败而非后端 flush 时
• ignorable: true 标记纯信息记录；缺省 = required（reader 遇到未识别类型必须 refuse 而非静默丢弃）

Surface 机制（模型可见历史）#

三个消息产生型事件（SurfaceEventType: user/message, assistant/message, tool/result）带 SurfaceOp：

• 'append' — 正常尾部追加
• { op: 'replace', start, end } — 用新节点替换 start..end 表面节点（compaction 用）

Session.surface 是 readonly live 投影；deriveMessages() 按 surface 节点顺序折叠派生模型历史。compaction 通过 replace 把一段 surface 摘要成一个 user/message，被影子的原始事件仍在日志中（可审计、可追溯）。

为什么这是上下文管理的根基#

1. 重放保真：raw assistant/chunk 保留 token 级流式细节，UI 渲染和重放一致
2. 可压缩：surface replace 让 compaction 无模型改写历史，影子节点不丢
3. 可派生：fork、resume、transcript、telemetry、title 全部从同一 log 派生
4. 可持久化：SessionPersistence seam（JSONL / SQLite 后端）+ session/flush checkpoint + 崩溃恢复
5. 可审计：坏事件源头拒绝；unrecognized 事件 refuse 而非静默丢

相关类型#

• EpochHeader（request/header 事件）：call config + adapterDefaults + system + tools，最新快照重构；foldRequestHeader(events) 选择最新 snapshot
• Branded ID：CallId（工具调用关联）、SessionId（agent/session 共享身份）—— 跨包边界类型安全

Open Questions / Debates#

• 日志增长 → 需要 compaction（surface replace）作为一等公民；token-meter 测量影子内容
• 事件溯源 vs 直接存消息数组：前者强在重放/审计/派生，后者简单但不可重放

DeepSeek Harness（dsh）是 2026 年 DeepSeek AI 开源的 agent harness。本文把它与 wiki 中已有的同类框架对比，帮助定位"agent 运行时"这个设计空间的各条路线。对比维度：架构范式、可替换性、会话模型、执行后端、生态。

Comparison Table#

关键差异解读#

dsh vs LangGraph（图编排 vs 插件运行时）#

• LangGraph 把 agent 工作流建模为 graph 状态机（节点 = 工具/LLM/子图），显式编排
• dsh 不规定图：核心是事件溯源会话 + 可替换能力 + 插件运行时，工作流只是可挂载的插件（workflow seam），loop 本身也是插件
• 启示：图的显式性适合可预测流程；插件运行时的灵活性适合"agent 即操作系统"的产品形态

dsh vs OpenHarness（框架 vs 复刻）#

• OpenHarness 是 Claude Code 的行为复刻（engine + tools + permissions + hooks + swarm），API 形状学 Claude Code
• dsh 是通用框架，甚至可以把 Claude Code/Codex 桥接进来（hooks-claude-code / hooks-codex）
• dsh 的 capability seam 允许一个 harness 承载不同 agent 产品；OpenHarness 目标是"像 Claude Code 的开源替代"

dsh vs nanobot / OpenClaw（重 vs 轻）#

• nanobot/OpenClaw 追求超轻量个人 agent（本地模型、简单 loop、快速上手）
• dsh 是生产级规模（~130+ 包、事件溯源、沙箱、双语文档、1372 Agent Notes）—— 学习成本高，但架构决策密度极高

Verdict#

对 Agentic System Designer 职业路径：

• 想快速做个人 agent → nanobot / OpenClaw 路线
• 想理解 Claude Code 产品形态 → OpenHarness / learn-claude-code
• 想学生产级 harness 架构（事件溯源、capability seam、插件运行时、Host/Client 双面 TS 工程）→ DeepSeek Harness 是目前最完整的开源参考，且是唯一国内顶级大厂开源的同类项目

AI 优先、人类其次。 Ling is an AI-first, Chinese-English bilingual programming language. The codemap (LCN — Ling Canonical Notation) is the canonical IR; source code is a projection of it. Built by the wiki maintainer (jiangh_hnr on gitcode).

• Repo: git@gitcode.com:jiangh_hnr/ling-lang.git
• Version (this clone): v0.0.6 (Cargo.toml; effect-system milestone)
• License: MIT
• Status: experimental, pre-1.0 — design phase complete (27 ADRs locked), implementation in progress (v0.0.6 = effect-system baseline)
• Web: https://ling-lang.dev
• Implementation: Rust 2021, targeting LLVM 20
• Install (AI-first): curl -sSL https://ling-lang.dev/install | sh — daemon runs in background, MCP auto-registered
• Install (Rust dev): git clone ... && cargo install ling

What It Is#

Ling is a programming language designed so that AI agents are the primary authors and readers of source code; humans are reviewers. Three commitments follow from this:

1. AI-first, human-second. Not a "human-first with AI support" or "dual first-class" — single-customer choice, with all the design implications that follow.
2. Codemap is the canonical IR. Source code is a projection of codemap, not the other way around. Codemap is bidirectional (code → codemap, codemap → code), regenerable, schema-enforced, and gitignored (derived, like target/).
3. AI consumes codemap via MCP/LSP tools, not by direct file I/O. The .lcn files are a serialization target, not the primary AI interface (ADR 0027).

The most distinctive feature compared to other AI-first languages (see Zerolang): Ling's canonical IR is document-shaped (LCN, S-expression, with structured + narrative fields), whereas Zerolang's is graph-shaped (zero.graph). The choice cascades through everything: edit surface, MCP/LSP design, human review style.

L1-L4 Architecture#

L1 Strategic  Naming / version path / AI-first       0001–0003
L2 Language    Type system / memory / effects / form  0004, 0005, 0012–0015
L2.5 Codemap   LCN format / schema / sync / AI access        0006–0011, 0024–0027
L3 Compiler    Frontend / MIR / error recovery / incremental  0016–0020
L4 Backend     LLVM / Cranelift / wasm / signing              0023
L4 Quality     Test strategy / perf budget / CI gates         0021, 0022

The 27 ADRs are immutable — to reverse, write a new ADR that supersedes. The .harness/docs/ai-first-checklist.md is a hard-rule gate on every PR.

The Compiler Pipeline (κᵧ)#

Source (.ling) → Scanner (bilingual, indentation-aware)
              → Tokens (per-line tokenize_line)
              → Parser (indent → S-exp, type/symbol resolution)
              → AST (parse-time, discarded)
              → Codemap extractor
              → Codemap (CANONICAL IR; in-memory + .ling/codemap/;
                         daemon-owned, regenerable, gitignored)
              → MIR derivation (per backend: LLVM, Cranelift, wasm)
              → Backend → artifact (.ll / .o / .wasm / binary)

This is the strongest possible form of "codemap is the design surface" — the AI consumes exactly what the compiler uses. The trade-off: codemap schema is the highest-stakes contract in the project, and implementation effort is higher than traditional pipelines initially.

LCN — Ling Config Notation (S-Expression Format)#

Same syntax family as .ling source. Files use .lcn extension. The same parser handles both (modulo codemap-specific fields). Codemap fields are both structured (types, signatures, effects, call graph edges, schema-enforced) and narrative (intent_markdown, design_notes, examples, CommonMark + extensions).

(模块 ling_std.core
  (函数 swap
    (参数 [(a Int) (b Int)])
    (返回 Unit)
    (效应 [])
    (意图 "原地交换两个整数。\n\n**为什么不做泛型**: `swap<T>` 在 v0.0.x 被砍掉,理由是 codemap 暴露了所有 call site,AI 看到 monomorphic 版本足够。")
    (调用方 [sort sort_desc test_swap_basic])
    (示例 [(输入 "a=1, b=2" 输出 "a=2, b=1")])
  )
)

The narrative 意图 field is the key differentiator from pure graph-based IRs (like Zerolang's zero.graph). It lets designers embed why alongside what, in a way that the codemap schema can validate structurally while the narrative is freeform.

Effect System — Pure-First, Short-Tag (组合 1)#

Standard short-tag vocabulary: !FS, !Net, !Clock, !Rand, !Panic, !IO (catch-all), !pure (optional explicit).

Core rules:

1. Default = pure. No tag = pure. Purity is proven by the reverse-check pass, not assumed.
2. Purity is reverse-checked. For any untagged function, the compiler scans the body for IO-tagged calls. If found, the function must be tagged.
3. IO functions must declare a short tag from the standard vocabulary.
4. Codemap stores the full effect set for every function.
5. Effect subtyping: v0.0.x is equal-or-disjoint; subtyping rules deferred to v0.1+.

The reverse-check is finite and decidable — implementable in ~1 week, vs multi-month research for full effect inference.

Language Form — ι Integrated (ADR 0015)#

Visual indentation + internal S-expression. The .ling source is indentation-sensitive (2-space); the AST and codemap are S-expressions. One parser family, three views.

Bilingual keywords are the same TokenKind variant — 让 and let both map to KwLet. Twelve keyword pairs (模块/module, 函数/fn, 让/let, 可变/mut, 返回/return, 如果/if, 另则/else, 遍历/for, 在/in, 只要/while, 模式 (no English)). This is unique among the AI-first languages known to the wiki.

Daemon Model (ADR 0024) — Hybrid#

trait CodemapBackend {
    fn lookup_symbol(&self, q: &SymbolQuery) -> Result<Vec<SymbolEntry>>;
    fn query_effects(&self, q: &EffectQuery) -> Result<Vec<EffectEntry>>;
    // ...
}

Two implementations: DaemonBackend (Unix socket / named pipe to ling daemon, in-memory codemap) and FileBackend (reads .ling/codemap/<module>.lcn from disk, no daemon required). Both return identical Result types; the compiler is unaware of which is in use. Used in: long-running AI sessions (daemon, fast) vs CI / fresh dev (file, no daemon).

Performance Budget (ADR 0022)#

AI Team Harness (6 reins)#

The .harness/ directory defines a 6-role team with an orchestrator:

• strategist — L1 strategic decisions
• language-designer — L2 language-layer ADRs
• codemap-architect — L2.5 codemap ADRs
• compiler-engineer — L3 compiler pipeline
• backend-engineer — L4 backend (LLVM, Cranelift, wasm)
• quality-engineer — L4 quality (tests, perf, CI)

.harness/docs/ai-first-checklist.md is a hard-rule gate on every PR. .harness/docs/adr-map.md tracks per-rein ownership of ADR areas.

Roadmap#

v0.0.1  scanner + parser + codemap LCN renderer          ✅ done
v0.0.2  控制流 (if/else) + let 绑定 + 二元运算 + fib      ✅ done
v0.0.3  for/while/match + list types + 模块导入/导出       ⏳ next
v0.0.4  Option/ADT types + user-defined types
v0.0.5  mut bindings + region inference (区域推导 β)
v0.0.6  效应系统基础 !FS / !Net / !Clock                  ✅ done in Cargo.toml
v0.1.0  完整 type checker / MIR + LLVM 后端 + 泛型 + 可重现构建
v0.2.0  trait + Cranelift 后端
v0.3.0  完整效应 + wasm 后端 + codemap 稳定 schema
v1.0    生产可用: 全后端稳定 + 完整 stdlib + LSP + 包管理

Note: Cargo.toml is at v0.0.6 and effect-demo.ling references v0.0.6 with working !FS tags — so the effect-system milestone is done. README's "v0.0.3 next" status block is slightly stale.

Hard Engineering Rules (from AGENTS.md)#

• No unwrap() / expect() in non-test code — emit a Diagnostic instead.
• ADRs are immutable. Reverse = new ADR that supersedes.
• Bilingual keywords are the same TokenKind variant; one tokenizer.
• Indentation-aware parsing (2-space); split_logical_lines() tracks indent per line.
• Per-line tokenization — tokenize_line() called per logical line.
• Parser always returns a Module (never panics). Unrecoverable sections become Stmt::Invalid; errors accumulate in DiagnosticBag.
• No GC, ownership-based memory via region inference.
• AI-first checklist gate on every PR.

Key Concepts (each has a wiki page)#

• Codemap as Design Surface — the core thesis (codemap is canonical, source is projection)
• Effect System Pure-First — 组合 1 (pure-first + short-tag + reverse-check)
• LCN S-Expression Format — LCN as codemap serialization (S-expression, .lcn extension)

Relationships#

Direct comparison#

• AI-First Programming Languages — Ling vs Zerolang vs Others — the comparison page that pairs this with Zerolang and others

Related entities#

• Zerolang — the other known AI-first programming language; graph-based IR vs Ling's document-based IR
• 12-Factor Agents — shares the "AI-first / context-engineering" posture; Factor 5 (own your context window) is the policy-level cousin of codemap-as-IR
• MCP (Model Context Protocol) — the primary AI access pattern to codemap (ADR 0027), not just a nice-to-have
• pi-coding-agent (archived — moved to entities/) — analogous split (7 tools, 4 modes) at the agent-harness layer
• oh-my-openagent — agent harness with maximum-function-set
  • Hook philosophy; Ling attacks the same problem at the language layer with a minimum + codemap design

Related concepts#

• Codemap as Design Surface
• Effect System Pure-First
• LCN S-Expression Format
• agent-loop-architecture — ling query * and MCP tools implement a narrow agent loop for code authoring
• Agent Design Principles — Ling's 6 hard indicators of safe delegation are first-class design principles
• Context Engineering — codemap is context-engineering at the program level: structured + narrative fields
• Graph-Native Programming — Zerolang's cousin thesis
• Semantic Patch Editing — Zerolang's edit primitive; Ling uses MCP tools instead of patch operations
• Program Graph Store — Zerolang's program database; Ling's codemap is document-shaped, not graph-shaped
• Projection as Source View — Zerolang's projection model; Ling's .ling source is also a projection of codemap but the design is bidirectional (codemap → code is first-class)

The programming language for agents. Graph-native, by Vercel Labs. zero.graph is the program. .0 files are projections of it. Edit through zero patch. — vercel-labs/zerolang

• Repo: vercel-labs/zerolang
• Version (this clone): v0.3.4 (workspace package.json)
• License: Apache-2.0
• Status: experimental, pre-1.0 — "expect breaking changes, rough edges, and security issues. Run it in isolated workspaces, not against production systems or sensitive data" (README)
• Web: https://zerolang.ai
• Install: curl -fsSL https://zerolang.ai/install.sh | bash
• Agent bootstrap: npx skills add vercel-labs/zerolang

What It Is#

Zerolang is a graph-native programming language explicitly designed for agents. The semantic graph (zero.graph) is the program database; the agent's normal authoring surface is a set of graph operations (zero query, zero patch, zero check, zero test, zero run). .0 files exist as human-readable projections — reviewable, bidirectionally syncable, but not the normal agent write surface.

It is, in a precise sense, an attempt to redesign the programming language itself around the agent's edit surface. The agent no longer writes text and hopes the compiler accepts it — the agent queries the graph and submits a checked semantic patch, which the compiler accepts or rejects before the store is written.

Architecture (one-paragraph)#

A graph-first package contains zero.toml (manifest), zero.graph (checked binary store, content-hashed), and src/main.0 (readable projection). The normal package compile path is:

zero.graph → repository graph tables
  → semantic validation → type checking
  → MIR + backend facts → direct codegen → artifact

zero.graph is loaded directly — no parse-first stage on the normal path. This is the same shape as a parse-first pipeline (lexer → AST → name resolution → type check → IR → codegen) with fewer stages and a graph input instead of text.

The 8 native build targets are darwin-arm64, darwin-x64, linux-arm64, linux-musl-arm64, linux-musl-x64, linux-x64, win32-arm64.exe, win32-x64.exe. The C-implemented compiler lives at native/zero-c/; a bin/zero wrapper execs the local native compiler at .zero/bin/zero.

Key Concepts (each has a wiki page)#

• Graph-Native Programming — the core thesis: semantic graph is the program database, not text.
• Program Graph Store — zero.graph as a binary, content-hashed, shape-validated store with explicit projection/sync boundary.
• Semantic Patch Editing — checked graph patches (--expect-graph-hash, --expect, typed ops, replaceFunctionBody, replaceBlockBody) vs text diffs.
• Projection as Source View — .0 files as the reviewable, bidirectionally-syncable human surface; export / import / verify-projection / status, content-hash drift detection.

CLI Surface (graph-first agent work)#

Core commands (defaults to current directory):

zero init [--template cli|package]
zero query [--fn <name>] [--find <substr>] [--refs <name>] [--calls <name>]
zero view --fn <name>
zero patch --op '<op>' | --check-only | --dry-run
zero check
zero test
zero run -- <args>
zero build --emit exe|obj|llvm-ir --target <target> --out <path>
zero diff
zero inspect --json          # node IDs, graph hashes, interfaceFingerprints,
                             # targetToolchains, usedStdlibHelpers,
                             # memoryBudgets, releaseTargetContract
zero size --json
zero mem --json
zero targets --json
zero doctor --json
zero skills [get <name>]     # version-matched bundled skills
zero explain <diagnostic-code>
zero fix --plan

Patch operations cover surgical in-function edits (--replace-in-fn <fn> --old <text> --new <text>, Edit semantics) up to bulk helper creation (upsertFunction ... end) and whole function bodies (--replace-fn <fn> --body-file - with a heredoc).

The Agent Loop (per day)#

For most package work:

zero query                   # ask the graph for facts
zero patch --op help         # discover available operations
zero patch --op 'addMain'    # checked semantic edit
zero check
zero test
zero run -- <args>

When a human wants to review projection text:

zero export
zero verify-projection

When a human intentionally edited a projection:

zero import
zero check

Language Surface (highlights)#

• Functions: fn add(x: i32, y: i32) -> i32 { return x + y }
• Fallible functions: use raises and check — no hidden exceptions

  fn requirePositive(value: i32) -> i32 raises [Invalid] {
      if value > 0 { return value }
      raise Invalid
  }
  

• Explicit capabilities: programs receive capabilities explicitly (e.g. world: World) — no ambient global runtime access. The 33-module stdlib documents effects and target support per helper.
• Blocks as graph nodes: while, match, if/else all lower to explicit graph control-flow nodes. Agents can patch a whole function body or a specific block body (replaceBlockBody #block_then_1234 ...).
• Compile-time facts: a small metadata surface for target and type facts (integer/Bool/enum static values, compileTime, target.pointerWidth, fieldType, hasEnumCase).
• Modules: src/foo.0 defines module foo; src/foo/mod.0 defines directory module foo. Import cycles and duplicate public exports are diagnosed before build output.

The 33 stdlib modules are: args, ascii, cli, codec, collections, crypto, csv, diag, env, fmt, fs, http, inet, io, json, log, math, mem, net, parse, path, proc, rand, regex, search, sort, str, testing, text, time, toml, unicode, url. The stdlib skill is ~39 KB of full signature reference, including ready-made validators (std.time covers RFC 3339 incl. leap seconds, std.inet covers IPv4/IPv6/hostname, std.regex is ECMA subset, std.unicode is strict UTF-8).

Runtime Goals (non-negotiable)#

The graph-first model should reduce agent guessing without relaxing:

• token-efficient inspection
• low memory usage
• fast startup and builds
• low runtime latency
• explicit capabilities
• small, dependency-free artifacts

These are inspectable per-graph-input via zero size --json, zero mem --json, and the benchmark docs.

Version-Matched Skills (key agent-facing pattern)#

The thin external vercel-labs/zerolang skill is a discovery stub only. The compiler bundles version-matched skills — fetch each topic at most once per session (content is fixed for a given binary):

zero skills
zero skills get agent       # ~4 KB
zero skills get language    # ~6 KB
zero skills get graph       # ~9 KB
zero skills get diagnostics # ~4 KB
zero skills get packages    # ~5 KB
zero skills get builds      # ~5 KB
zero skills get testing     # ~3 KB
zero skills get stdlib      # ~39 KB
zero skills get stdlib --topic std.time   # one section only

If multiple Zero binaries exist, use the one that will run the project.

Things Intentionally Not Hidden#

• hidden method registries
• vtables
• reflection
• ambient heap allocation
• process-global cleanup lists

When a program uses owned resources, allocator state, hosted I/O, network capability, or C interop, those facts should be visible through graph inspection and diagnostics.

Boundaries#

• Pre-1.0, experimental. Breaking changes are expected; the contributor policy (AGENTS.md) says explicitly: "Do not preserve legacy behavior by default. Prefer the clearer agent-facing design over compatibility shims, migration layers, or carrying old paths forward."
• Not for production. No security audit; isolate in disposable workspaces.
• C-implemented compiler under native/zero-c/ — the agent-facing CLI is in front of a C backend, not a self-hosted VM.

Repository Layout (this clone)#

zerolang\
├── AGENTS.md           # contributor + safety policy
├── README.md           # the thesis + the daily loop
├── package.json        # v0.3.4, pnpm workspace
├── native/zero-c/      # C-implemented compiler
├── bin/zero            # wrapper → .zero/bin/zero
├── std/                # 33 stdlib modules
├── examples/           # 165 .graph + .0 example pairs
├── docs/articles/      # human-readable reference
│   ├── concepts/{graph-architecture, projections, semantic-vs-text, compile-path}.md
│   ├── modules/        # one .md per stdlib module
│   ├── cli-reference.md
│   ├── language-reference.md
│   ├── primitives.md
│   ├── testing.md
│   ├── package-manifest.md
│   ├── standard-library.md
│   ├── c-interop.md
│   ├── cross-compilation.md
│   ├── diagnostics.md
│   ├── target-capabilities.md
│   ├── optimization.md
│   ├── examples.md
│   ├── learn-zero.md
│   └── install.md, getting-started.md, building-from-source.md, benchmarks.md
├── skills/zero/SKILL.md
├── skill-data/         # 8 version-matched bundled skills
├── extensions/vscode/
├── benchmarks/{rosetta, zero}/
├── evals/
├── conformance/        # ~50 conformance fixtures + agent-surface tests
├── tests/
└── scripts/            # pnpm scripts: agent:checks, conformance, etc.

Relationships#

Related entities#

• Vercel Labs — the organization behind it
• 12-Factor Agents — shares the "agent-first / context-engineering" posture; Factor 5 (own your context window) and Factor 13 (pre-fetch vs ask) are explicit cultural cousins
• pi-coding-agent (archived — moved to entities/) — analogous split: 7 tools, 4 modes, ~3,100 LOC AgentSession. Zerolang attacks the same problem at the language layer instead of the agent harness layer
• oh-my-openagent — agent harness with maximum-function-set
  • Hook philosophy; Zerolang is the minimum-surface-language counterpart (zero patch ops are deliberately narrow)
• LangGraph — graphs the agent's state machine. Zerolang graphs the program being authored. Different layer, same word.
• Claude Code — the agent harness that would most naturally drive a zero patch loop

Related concepts#

• Graph-Native Programming — the core thesis
• Program Graph Store — zero.graph as a binary store
• Semantic Patch Editing — checked graph patches
• Projection as Source View — .0 files as human review surface
• agent-loop-architecture — Zerolang is a narrow agent loop (query → patch → check/run) for a single domain (code authoring)
• Context Engineering — zero query is exactly the pre-fetch-vs-ask pattern from 12-Factor Factor 13
• Agent Design Principles — Zerolang embodies several principles: tool ergonomics, deterministic inspection/repair, regular patterns over syntactic convenience

2026-06 更新。聚焦两门已知公开的 AI-first 编程语言设计: Ling (灵)（灵, v0.0.6, 27 ADRs, codemap-as-design-surface） 和 Zerolang（v0.3.4, graph-native, zero patch）。 同时纳入另外 4 个 PL/PL 设计做参照（Mojo、Carbon、APL/J/K 系、 JetBrains MPS），看 AI-first 是孤注一掷还是新趋势。

一句话定位#

重点对比的两门：

• Ling 是用户的项目（27 ADRs 锁设计，27 ADRs 不可变）
• Zerolang 是外部项目（v0.3.4, 较成熟但仍未 v1.0）

核心范式对比#

Canonical IR 形态对比#

核心差异：

• Ling 把"design rationale"做成了 codemap 的一等字段 (意图, 设计笔记)。AI 看 structured, human 看 narrative。
• Zerolang 把所有 metadata 都做成 graph node, 没有"narrative"的等价物。
• 传统 PL 把所有 design rationale 放在注释里, 不是 schema-enforced。

Edit Primitive 对比#

类型 + 安全模型对比#

Performance Budget (AI 视角)#

Ling 给了详细的 AI-场景性能预算 (ADR 0022)。Zerolang 没明说，但有 zero size --json, zero mem --json, benchmark docs。

关键观察： Ling 把 daemon + MCP round-trip 当作 AI 路径的关键路径指标，Zerolang 不假定 daemon，直接走 zero patch 命令。

Daemon / Background Process 对比#

AI 工具集成#

何时选哪个？#

哲学 / 设计哲学差异#

共同的设计哲学 (与主流 PL 对比)#

两门 AI-first PL 都有这些与主流不同的核心点：

1. Canonical IR ≠ text — 都是"text is a projection"。Zerolang 用 binary graph, Ling 用 LCN document, 但都不是"text 是一等公民"。
2. AI edit 走显式路径 — Zerolang zero patch, Ling MCP tool。不假定 AI 直接改文本。
3. Drift 是显式管理的 — Zerolang 用 content-hash 决定 RGP006, Ling 用 daemon-owned codemap 强制 schema 一致。
4. 安全 = reviewer-visible — Zerolang capabilities, Ling effects, 都是为了让 human reviewer 在签名层就能看到函数能不能 IO。
5. Schema 强约束 — Zerolang shape-validated graph, Ling structured+narrative fields with enforced schema。
6. Pre-1.0 experimental — 都明确说"pre-1.0, expect breaking changes, use in isolated workspaces"。

不确定的 / 待观察#

• MCP 集成的成熟度： Ling 把它作为 critical path, 但 v0.0.6 还没到 LSP/MCP 阶段 (按 roadmap 是 v0.1.0+)。Zerolang 没有 MCP 集成, 但有 zero skills bundled skills 作为 agent knowledge 来源。两种模式哪个更 work, 需要 2026-2027 看实际使用。
• Codemap 双向同步的实际可行性： Ling ADR 0025 说 statement+function 粒度 sync, 但双向同步的 conflict resolution 在真实使用中可能比预期复杂。
• Graph vs Document IR 的胜出： 长期看, agent 是否会偏好 graph (structural queries) 还是 document (narrative queries)? 取决于什么样的 query 最常见。如果 "what does this function mean" 重要, Ling 赢; 如果 "what calls this" 重要, Zerolang 赢。
• Effect system vs Capabilities 的胜负： 两个不同的安全模型, 都在为同一目标 (reviewer-visible side effects) 服务。哪个更 AI-friendly, 需要 2027+ 观察。

关键 takeaway#

• AI-first PL 设计已经分化为两派：graph-based (Zerolang) vs document-based (Ling)。
• 两种都拒绝"text is source of truth", 都在 explicit 编辑路径, 都有 reviewer-visible 安全机制。
• Ling 的独特优势： design rationale (narrative fields), 中英双语, MCP/LSP 集成是 critical path。
• Zerolang 的独特优势： graph-based structural guarantees, hash-based drift detection, content-hash 的"哪个 side moved"判断。
• 两者都不是给"AI 加速"用的 (像 Mojo); 都是"为 AI 作者/读者"重新设计的 PL。

Codemap is the canonical IR. Source code is a projection of codemap. Three things flip from the parse-first mainstream.

The "codemap as design surface" idea, formalized in ADR 0006 of Ling (灵), is the most distinctive commitment in any AI-first programming language known to the wiki. The original paradigm shift framing:

The author's framing of why:

"AI Agent 工作流永远都是文档驱动的,所以设计优先显得尤为重要。 Codemap 除了派生、亦可以作为比 Markdown 还好用的 AI 文档。AI 既 可以通过 Codemap 设计代码、可以根据代码派生 Codemap。"

Why "design surface", not just "data structure"#

The codemap is a design surface, not just a data structure, because:

• It is the interface AI uses to reason about the program. A query like "what functions touch the filesystem?" returns from codemap, not from the parser + analyzer pipeline.
• It carries both structured (types, signatures, effects, call graph edges, schema-enforced) and narrative (intent_markdown, design_notes, examples, CommonMark + extensions) fields. Narrative is first-class, not a comment.
• It is bidirectional in the design sense: code → codemap and codemap → code are both first-class. You can author by editing source and re-extracting, or by editing codemap and regenerating source.

Bidirectional sync (ADR 0006, 0025)#

• code → codemap: Continuous extraction (codemap is synced as source edits happen; v0.0.4+ adds a daemon that keeps codemap in-memory)
• codemap → code: AI or human edits codemap; source is regenerated
• Both directions are first-class

Sync granularity is statement + function level (ADR 0025) — invisible to the AI; AI just sees consistent codemap.

The "structured + narrative" split#

(function_entry
  ; structured (schema-enforced)
  (name "swap")
  (params [(a Int) (b Int)])
  (return Unit)
  (effects [])

  ; narrative (CommonMark + extensions)
  (意图 "原地交换两个整数。\n\n**为什么不做泛型**: `swap<T>` 在 v0.0.x 被砍掉,理由是 codemap 暴露了所有 call site,AI 看到 monomorphic 版本足够。")
  (示例 [(输入 "a=1, b=2" 输出 "a=2, b=1")])
)

This is the key differentiator from a pure graph-based IR like Program Graph Store (Zerolang's zero.graph). The narrative fields let designers embed why alongside what — in a way that the codemap schema validates structurally while the narrative is freeform. The example above is from ADR 0007.

AI access pattern (ADR 0027) — MCP/LSP, not direct file I/O#

A later clarification (ADR 0027) re-framed how AI agents interact with codemap. The original framing in ADR 0006 was "AI reads codemap." The clarification:

"AI Agent 对 Codemap 写法并不一定非要学习,因为我们定义了工具链 MCP/LSP,可以通过 tools 直接给 AI 查询/编辑。AI 仅在设计阶段 可通过 Codemap 写设计。"

The primary AI access pattern is via MCP/LSP tools, not by direct .lcn file I/O. Concretely:

The implication: build great MCP tools, not pretty .lcn readers. This is why MCP (MCP (Model Context Protocol)) is a critical-path implementation for Ling, not a nice-to-have.

Relationship to Graph-Native Programming#

Both Ling and Zerolang agree on the "canonical IR" idea; they disagree on the shape of that IR and on the edit surface.

The shape choice cascades through everything. Graph IR is good for structural queries ("what calls write?"); document IR is good for structural + narrative queries ("what does swap mean and why was generics deferred?").

What this enables (Ling-side)#

• MCP/LSP become thin shells over codemap queries (ADR 0016) — no separate query engine, no two-truths problem
• AI tool results match compiler-internal results byte-for-byte — single source of truth
• Repository stays source-dominated (codemap gitignored) — like target/ in Rust
• Codemap review = compiler-internal review — humans and AI see the same data
• Reproducible builds (ADR 0023) — any agent with source can derive identical codemap

What this costs#

• Codemap schema becomes the highest-stakes contract in the project. If codemap has a bug, every downstream stage is affected. Mitigation: codemap is regenerable from source; ling codemap rebuild recovers.
• Implementation effort higher than traditional pipelines initially. One-time investment; long-term benefit (shared data structure).
• All "compiler internals" thinking is now "codemap thinking" — requires team upskilling.

Default = pure. IO must be tagged. Purity is proven, not assumed.

The "pure-first, short-tag" effect system (formalized in ADR 0013 组合 1 of Ling (灵)) is one of the most pragmatic effect-system designs known to the wiki. It satisfies the L1 "safe delegation" requirement (humans reviewing AI code can see, at the signature level, which functions have which side effects) without the verbosity of fully-explicit effect sets or the implementation risk of full effect inference.

Why an effect system at all#

Per ADR 0002 (L1 strategic layer), the "safe delegation" hard indicator #5 is explicit side effects, mandatory at v0.1. This means: when an AI writes a function, the human reviewer must be able to see, at the signature, which functions are pure and which touch state. A function that "looks pure" but secretly reads the network is a safety violation.

The four design candidates considered#

Core rules#

1. Default = pure. A function with no effect annotation is treated as pure. Purity is proven, not assumed.
2. Purity is reverse-checked. For any function without an effect tag, the compiler scans the function body for any IO-tagged call. If found, the function must be tagged with that effect.
3. IO functions must declare a short tag drawn from the standard effect vocabulary.
4. Codemap stores the full effect set for every function (inferred, declared, or proven).
5. Effect subtyping: for v0.0.x, effects are equal-or-disjoint (no automatic subtyping). Subtyping rules can be added in v0.1+.

Standard short-tag vocabulary#

Multiple tags: !FS,!Clock (comma-separated). For v0.0.x, max 3-4 tags; complex effect combinations get explicit sets in v0.1+.

Concrete examples#

;; Pure: no tag, no IO inside
(函数 square [x: Int] -> Int = {
  (返回 (* x x))
})

;; IO: tag required
(函数 read_file [path: String] -> String !FS = {
  (返回 (io_read path))
})

;; ERROR: tagged !FS but calls network operation
(函数 sneaky [url: String] -> String !FS = {
  (返回 (http_get url))
})
;; compiler error:
;;   error: function `sneaky` declared `!FS` but calls `http_get` (effect: Net)
;;   note: declare as `!FS,!Net` or remove the call

;; Multiple effects
(函数 load_config [path: String] -> Config !FS,!Clock = {
  (让 stats (file_stat path))    ;; !FS
  (返回 (Config (file_read path) (now)))  ;; !FS, !Clock
})

The reverse-check algorithm#

reverse_check(f):
  for each call site c in f's body:
    let callee = codemap.lookup(c)
    if callee.effects.is_nonempty():
      error: f is implicitly pure but calls {callee.name}
             which has effects {callee.effects}
  if no error: f.effects = {}

This is a finite, decidable check — the function body is finite, the codemap is finite. No inference involved; just lookup. The implementation is ~1 week of work vs the multi-month research of full effect inference.

Why 组合 1 wins on AI ergonomics#

• Most functions are pure; not having to tag them removes noise. Pure functions are the 70-80% case; the cost of !pure everywhere is real.
• AI doesn't need to remember to add !pure. It just leaves the tag off.
• Reverse-check ensures it's not laziness. If a function is implicitly pure, the compiler proves it. There's no way to "forget" an effect tag without the compiler catching it.
• Codemap always carries the full effect set for queries, review, and AI reasoning. Structured field, schema-enforced.
• Composability: reverse-check + codemap gives a complete effect flow graph.

The costs (with mitigations)#

Implementation phases#

• v0.0.6 — Effect tag parser, standard vocabulary, reverse-check pass, codemap records effect sets (✅ done in this clone)
• v0.1.0 — Effect subtyping (pure ⊆ {FS}), custom effect tags
• v0.2.0 — Effect polymorphism (when generics are introduced)

Codemap integration#

• Every function has an effects field in codemap (empty list for pure)
• AI queries: ling query effects !FS returns all functions touching the filesystem
• AI queries: ling query pure returns all pure functions
• Codemap diffs (per ADR 0010) show effect changes prominently

Comparison to other effect systems#

The Ling design is the most pragmatic of these: low AI cost, low implementation cost, and the safety guarantee is stronger than "trusted declaration" because purity is proven.