promptex-js 0.0.1-alpha.1 → 1.0.0

package/README.md

@@ -1,84 +1,121 @@
-# promptex-js（alpha 原型）
+# promptex-js
 
-promptex 的 TypeScript SDK **最小原型**。目前的能力只有一項：宣告 skill，
-建置成 Claude Code 的 `SKILL.md` 產物。
+Declare prompt resources in TypeScript, compile them into whatever your AI coding
+tool expects on disk.
 
-## 這不是什麼
+Skills, rules, agents, hooks, MCP servers and permissions are ordinary files in a
+directory tree, and every tool wants that tree laid out its own way. This package
+lets you declare each resource once and project the result onto a target platform.
+It ships the TypeScript SDK, a precompiled native binding to the shared core, and
+the `promptex` command line tool.
 
-本套件是早期 alpha，**不是**完整的 promptex。正式版的單一套件內含 SDK、核心的
-預編譯二進位綁定與完整命令列工具三者；本原型只有 SDK 的最窄一條路徑，命令列
-工具只有 `build` 一個動詞，沒有原生綁定、沒有多平台投影、沒有引用與關係圖、
-沒有安裝與所有權登記。
+## Install
 
-介面與產物格式在正式版之前都會變，不保證任何相容性。正式版發布時本原型會被
-整份取代。
-
-## 安裝
-
-```bash
-npm install promptex-js@alpha
+```console
+npm install promptex-js
 ```
 
-需要 Node.js 22.14 以上。
-
-## 用法
+## Minimal example
 
-把宣告寫在 `prompts/` 下：
+Declarations live in a `prompts/` directory. Anything you `define*` at module
+scope is registered when the file is evaluated.
 
 ```ts
-// prompts/skill.ts
+// my-project/prompts/review.ts
 import { defineSkill } from 'promptex-js'
 
-export const commitHelper = defineSkill({
-  id: 'commit-helper',
-  name: 'Commit 訊息協助',
-  config: { whenToUse: '當使用者要求撰寫 commit 訊息時使用' },
-  content: [
-    '依 Conventional Commits 撰寫：type(scope): subject。',
-    'subject 用繁體中文、50 字內，不以句號結尾；body 說明變更動機而非變更內容。',
-  ],
+defineSkill({
+  id: 'code-review',
+  name: 'Code Review',
+  description: 'Reviews a pull request for correctness and readability',
+  config: { whenToUse: 'Reviewing a pull request' },
+  content: 'Check correctness first, then readability.',
 })
 ```
 
-建置：
+Point the command line tool at the directory that *contains* `prompts/`:
 
-```bash
-npx promptex build
+```console
+$ npx promptex build --install my-project --out my-project --platform claude
+✓ Metadata written (graph + content)
+  wrote .claude/skills/code-review/SKILL.md
+Install report (claude)
+  Projected artifacts, 1: .claude/skills/code-review/SKILL.md
 ```
 
-產出 `./.claude/skills/commit-helper/SKILL.md`：
+Which writes:
 
 ```text
+my-project/.claude/skills/code-review/SKILL.md
+```
+
+```markdown
 ---
-name: commit-helper
-description: 當使用者要求撰寫 commit 訊息時使用
+name: code-review
+description: Reviews a pull request for correctness and readability
+when_to_use: Reviewing a pull request
 ---
 
-依 Conventional Commits 撰寫：type(scope): subject。
-
-subject 用繁體中文、50 字內，不以句號結尾；body 說明變更動機而非變更內容。
+Check correctness first, then readability.
 ```
 
-`.ts` 宣告檔不需要先經過建置步驟，命令列工具靠 Node 的型別剝離直接載入。
+Switch `--platform codex` and the same declaration lands in Codex's layout instead.
 
-### 命令列選項
+## Commands
 
-```text
-promptex build [--src <目錄>] [--out <目錄>]
+| Command | What it does |
+| :--- | :--- |
+| `promptex build <dir>` | Compile and refresh the framework metadata under `.promptex/`. No platform artifacts, no ownership registry, no pruning. |
+| `promptex build --install <dir>` | Compile, write the platform artifacts, record ownership, and prune what you deleted. This is the one to use for real installs. |
+| `promptex build --install --dry-run <dir>` | Show what `--install` would change, without writing anything. Add `--content --json` to get the bytes it would write. |
+| `promptex build --export <export-dir> <dir>` | Write the exact tree `--install` would write under `<export-dir>/<unit>/`, with no registry. The unit subtree is cleared first. |
+| `promptex build --watch <dir>` | Rerun the same flags (`build` alone, `--install` or `--export`) as sources change. |
+| `promptex manifest <dir>` | Answer registry queries from the current projection. |
+| `promptex init <dir>` | Scaffold a new project (`--lang ts`, `python` or `rust`). |
 
-  --src <目錄>   宣告檔所在目錄，預設 prompts
-  --out <目錄>   產物輸出目錄，預設當前目錄
-```
+Common flags: `--out <install root>` (single-directory mode), `--platform <name>` (`manifest` only), `--unit <unit name>`, `--json`, `--locale <tag>`.
 
-### 程式化呼叫
+## What you can declare
 
-```ts
-import { build, defineSkill, renderSkill } from 'promptex-js'
+`defineSkill`, `defineRule`, `defineAgent`, `defineInstruction`, `defineResource`,
+`defineHook`, `defineMcp`, `definePermission`, `defineAsset`, `defineDir`.
 
-defineSkill({ /* ... */ })
-const written = await build('.')
-```
+Per-platform native settings are not declared in your sources: they belong to the
+target, so you write them as `claude({ settings: { … } })` in `promptex.config.ts`.
+Keys pass through verbatim into that platform's own settings file and the framework
+keeps no allowlist.
+
+Content is composed with builders rather than hand-written markdown:
+`section`, `list`, `ordered`, `table`, `code`, `check`, `link`, `file`, `image`,
+`quote`, `details`, `divider`, plus the inline containers `inline`, `bold`,
+`italic`, `inlineCode` and `inlineLink`.
+
+Anything that takes children takes the same set: plain text, another builder's
+result, or a reference. That includes list items and table cells, so a step can
+link straight to the resource it depends on. `inline` is the unstyled container:
+it joins its children with no separator and emits no markup, which is what a
+whole sentence made of text and a reference needs.
+
+Larger projects add a `promptex.config.ts` with `defineConfig` to split the tree
+into units, and register third-party platforms with `defineTarget`.
+
+## Notes
+
+The command line tool runs your declarations directly with Node's built-in type
+stripping, so there is no separate transpile step and promptex does not impose a
+build toolchain on your project.
+
+Everything past evaluation — projection, install, registry, graph, diagnostics —
+happens in a shared Rust core called through an in-process native binding, not a
+subprocess. The Python and Rust packages call the same core, so identical
+declarations produce byte-identical output across all three.
+
+## Links
+
+- Source and issues: <https://github.com/promptex-ai/promptex>
+- Architecture notes: <https://github.com/promptex-ai/promptex/blob/main/docs/architecture.md>
 
-## 授權
+## License
 
-MIT OR Apache-2.0，見 `LICENSE-MIT` 與 `LICENSE-APACHE`。
+Dual-licensed under either of MIT or Apache-2.0, at your option. See `LICENSE-MIT`
+and `LICENSE-APACHE`.

package/bin/promptex.mjs

@@ -1,113 +1,19 @@
 #!/usr/bin/env node
-// promptex 命令列工具（alpha 原型）。
+// promptex 的命令列轉發殼。
 //
-// 只有一個動詞：`build`。載入來源目錄下的宣告檔，把登記處內的 skill 投影
-// 成 SKILL.md。正式版的其餘動詞（evaluate、declare、config、diagnostics）
-// 不在本原型範圍內。
-
-import { spawnSync } from 'node:child_process'
-import { readdir, stat } from 'node:fs/promises'
-import { join, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
-
-const USAGE = `promptex（alpha 原型）
-
-用法：
-  promptex build [--src <目錄>] [--out <目錄>]
-
-選項：
-  --src <目錄>   宣告檔所在目錄，預設 prompts
-  --out <目錄>   產物輸出目錄，預設當前目錄
-  --help         顯示本說明
-`
-
-/** 宣告檔的副檔名。`.ts` 依賴 Node 的型別剝離，不經過額外的建置步驟。 */
-const SOURCE_EXTENSIONS = ['.ts', '.mts', '.js', '.mjs']
-
-function parseArgs(argv) {
-  const args = { verb: argv[0], src: 'prompts', out: '.' }
-  for (let i = 1; i < argv.length; i += 1) {
-    const flag = argv[i]
-    if (flag === '--src' || flag === '--out') {
-      const value = argv[i + 1]
-      if (value === undefined) throw new Error(`${flag} 後面缺少值`)
-      args[flag.slice(2)] = value
-      i += 1
-    } else {
-      throw new Error(`未知的選項：${flag}`)
-    }
-  }
-  return args
-}
-
-/** 遞迴列出來源目錄下的宣告檔，依路徑排序讓載入順序不隨檔案系統而變。 */
-async function collectSources(dir) {
-  const entries = await readdir(dir, { withFileTypes: true })
-  const found = []
-  for (const entry of entries) {
-    const path = join(dir, entry.name)
-    if (entry.isDirectory()) found.push(...(await collectSources(path)))
-    else if (SOURCE_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) found.push(path)
-  }
-  return found.sort()
-}
-
-async function main() {
-  const argv = process.argv.slice(2)
-  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
-    process.stdout.write(USAGE)
-    return
-  }
-
-  const args = parseArgs(argv)
-  if (args.verb !== 'build') {
-    process.stderr.write(`未知的動詞：${args.verb}\n\n${USAGE}`)
-    process.exitCode = 1
-    return
-  }
-
-  const srcDir = resolve(args.src)
-  try {
-    if (!(await stat(srcDir)).isDirectory()) throw new Error('不是目錄')
-  } catch {
-    process.stderr.write(`找不到來源目錄：${srcDir}\n`)
-    process.exitCode = 1
-    return
-  }
-
-  const sources = await collectSources(srcDir)
-  if (sources.length === 0) {
-    process.stderr.write(`來源目錄沒有宣告檔（${SOURCE_EXTENSIONS.join('、')}）：${srcDir}\n`)
-    process.exitCode = 1
-    return
-  }
-
-  // 載入宣告檔與呼叫 build 必須共用同一個模組實例，登記處才看得到宣告；
-  // 兩邊都經 `promptex-js` 的 dist 進入點解析，因此指向同一個模組。
-  const { build, declaredCount } = await import('../dist/index.js')
-  for (const source of sources) await import(pathToFileURL(source).href)
-
-  if (declaredCount() === 0) {
-    process.stderr.write(`載入了 ${sources.length} 份宣告檔，但沒有任何 skill 被宣告。\n`)
-    process.exitCode = 1
-    return
-  }
-
-  for (const path of await build(resolve(args.out))) process.stdout.write(`${path}\n`)
-}
-
-// Node 未內建型別剝離時（22.18 之前）以旗標重跑一次，讓 `.ts` 宣告檔不必
-// 先經過建置步驟。已內建的版本不重跑，避免多開一個行程。
-if (!process.features.typescript) {
-  const result = spawnSync(
-    process.execPath,
-    ['--experimental-strip-types', new URL(import.meta.url).pathname, ...process.argv.slice(2)],
-    { stdio: 'inherit' },
-  )
-  process.exit(result.status ?? 1)
-} else {
-  await main().catch((error) => {
-    process.stderr.write(`${error.message}\n`)
-    process.exitCode = 1
-  })
-}
+// 邏輯住 `src/cli/main.ts`（發布物為 `dist/cli/main.js`），本檔只把 argv 交過去：
+// 命令列的接線與指令分派是 TypeScript 源碼的一部分，與 SDK 同受型別檢查
+// 與同一次 `tsc` 建置，不再是套件裡唯一沒有型別的那一批 `.mjs`。
+//
+// 靠 Node 內建的型別剝除執行作者源碼：作者的提示詞源碼是 TypeScript，求值即
+// 執行，用內建能力才不必把某套建置工具鏈的偏好強加給使用者專案。
+//
+// shebang 不帶 --experimental-strip-types：型別剝除自 Node 22.18 起已是預設，
+// 旗標多餘；而它留在 shebang 裡會讓本套件在 Linux 上完全無法執行 ── GNU 的
+// env 不拆解 shebang 後面的參數（需 -S），症狀是
+// `env: 'node --experimental-strip-types': No such file or directory`。
+// macOS 的 env 會拆，因此這個缺陷只在 Linux 顯現。下界由 package.json 的
+// engines 宣告。
+import { main } from '../dist/cli/main.js'
+
+await main(process.argv)

package/dist/adapter.d.ts

@@ -0,0 +1,151 @@
+import type { Kind } from './ir.js';
+import type { PluginEntry } from './plugin.js';
+import { type SelectSpec } from './registry.js';
+/**
+ * 降級或不支援的一筆記錄，與核心 `adapter::DegradeEntry` 同型（AC-098）：
+ * 欄位名與序列化形態逐一對應，`formatReport` 因此可以把整份報告原樣交給
+ * 核心格式化。
+ */
+export interface DegradeItem {
+    readonly kind: Kind;
+    readonly nodeId: string;
+    readonly feature: string;
+    /**
+     * 降級前後的強制力層級（AC-093 的三段封閉列舉）；純機制缺失（不支援）
+     * 而無強制力落差時省略。
+     *
+     * 第三方適配同樣填得出這兩個欄位，不是內建平台專屬：報告的形態一旦讓
+     * 內建適配表達得比第三方多，「官方與第三方使用同一組公開能力」
+     * （AC-097）就只剩宣稱。
+     */
+    readonly from?: Enforcement;
+    readonly to?: Enforcement;
+    readonly note: string;
+}
+/** 強制力階梯（AC-093）：機械閘 > 流程閘 > 措辭層，列舉封閉。 */
+export type Enforcement = 'mechanical' | 'processGate' | 'wording';
+/**
+ * 一次第三方投影的安裝報告，與內建平台的 `Report`／`EmitReport` 同一形態
+ * （AC-098）：降級與不支援兩類皆進報告，不得靜默丟棄，因此第三方與內建
+ * 平台的產物能一併呈現在同一份人讀輸出中，不需要另一套報告格式。
+ */
+export interface EmitReport {
+    readonly platform: string;
+    readonly emitted: readonly string[];
+    readonly degraded: readonly DegradeItem[];
+    readonly unsupported: readonly DegradeItem[];
+}
+/**
+ * 第三方 adapter 的公開介面（AC-097）：官方與第三方適配使用同一組方法。
+ * `entries` 讀本平台要產出的節點；`render` 依落點表渲染節點內容；
+ * `overrides`／`reserved` 讀本節點的平台覆寫與框架保留鍵；
+ * `unsupportedOverride` 記下沒有鍵值面時那筆不支援；`degrade`／`unsupported`
+ * 記錄能力落差；`report`／`hasNotes` 取出累積的落差記錄。
+ *
+ * 兩份累積清單為內部狀態、經 `report` 取出，不另以同名屬性暴露：兩個記錄
+ * 方法的名稱（`degrade`／`unsupported`）本身即介面的一部分，把清單也用同名
+ * 屬性暴露會與方法名相撞。三個 SDK 的方法集合完全相同，目前沒有自動比對；
+ * 少一個方法就是「這個生態的第三方適配做得到的事比另兩個少」。
+ */
+export interface AdapterContext {
+    /**
+     * 本平台要產出的節點（省略 kind 即全部）：已套用節點自身宣告的平台限定
+     * （`meta.targets`）與配置單元的分發選取（`select`），見
+     * `createAdapterContext`。
+     */
+    entries(kind?: Kind): readonly PluginEntry[];
+    /** 依落點表渲染節點內容（AC-100）：第三個參數是落點對照表，不是回呼函式。 */
+    render(entry: PluginEntry, selfPath: string, layout: ReadonlyMap<string, string>): string;
+    /**
+     * 本節點為本平台宣告的平台原生鍵覆寫（`config.platforms.{平台}`），未宣告
+     * 或宣告了空物件時回傳 `undefined`（ADR-004「空物件視同未宣告」）。
+     *
+     * 框架保留鍵（`promptex:` 前綴）已濾掉，回傳的每個鍵都是可原樣併進本平台
+     * 產物的原生鍵；保留鍵另由 `reserved` 取出。
+     *
+     * 這個方法存在的理由是「官方適配也只使用這組公開介面」（ADR-004）此前在
+     * 覆寫這一格只是宣稱：內建適配讀的是核心的 `adapter::platform_overrides`，
+     * 第三方適配只能自己走 `entry.def.config.platforms[平台]`，於是「空物件視同
+     * 未宣告」的判定與保留鍵的過濾各自重造。兩種失效都沒有訊號：判定漂移只在
+     * 特定宣告下現形，保留鍵漏濾則直接把框架的指令洩漏成平台不認得的欄位。
+     */
+    overrides(entry: PluginEntry): Readonly<Record<string, unknown>> | undefined;
+    /**
+     * 本節點宣告的框架保留鍵（`promptex:` 命名空間），鍵是保留鍵名、值是它的
+     * 字串值；未宣告時回傳 `undefined`。
+     *
+     * 保留鍵是「覆寫的鍵即平台原生鍵」這條形態唯一的例外：它是寫給框架的指令，
+     * 由框架消費、不寫進產物（ADR-004）。宣告位置與值形態的錯誤已在投影入口以
+     * `E203` 阻斷，本方法回傳的都是合法且可直接使用的值。現行保留鍵只有
+     * `promptex:event`（僅 hook 合法）。
+     */
+    reserved(entry: PluginEntry): Readonly<Record<string, string>> | undefined;
+    /**
+     * 本節點在本平台的產物沒有承載鍵的位置時，把該筆記進不支援清單；節點未宣告
+     * 覆寫時什麼都不做。
+     *
+     * `form` 由呼叫端寫出本平台該類型的產物形態：哪些類型在本平台沒有鍵值面是
+     * 平台知識、住各適配（ADR-009），但「宣告的覆寫沒有落點」這件事對作者的意義
+     * 每個平台相同，訊息模板因此共用核心那一份。
+     */
+    unsupportedOverride(entry: PluginEntry, form: string): void;
+    /** 記錄能力降級，進安裝報告。 */
+    degrade(item: DegradeItem): void;
+    /** 記錄平台不支援而未產出的節點，進安裝報告。 */
+    unsupported(item: DegradeItem): void;
+    /**
+     * 把本次累積的降級與不支援併成安裝報告；`emitted` 由呼叫端依實際寫出的
+     * 產物決定，不在本介面判斷。
+     */
+    report(platform: string, emitted: readonly string[]): EmitReport;
+    /**
+     * 是否累積了任何降級或不支援記錄：擴充路徑據此決定要不要印報告（無落差時
+     * 多印一份空報告只是噪音）。
+     */
+    hasNotes(): boolean;
+}
+export type AdapterEmit = (ctx: AdapterContext) => Map<string, string>;
+/**
+ * 第三方適配的 target：與內建 `claude()`／`codex()` 回傳同一種 `{ platform
+ * }` 形狀，多帶一個 `emit` 實作（AC-099）。`defineConfig` 的 `targets`
+ * 陣列因此可與內建平台原樣並列宣告，schema 不因擴充而改變。
+ */
+export interface AdapterTarget {
+    readonly platform: string;
+    readonly emit: AdapterEmit;
+    /**
+     * 本適配接受哪些建構參數，標準 JSON Schema（ADR-013）。形態與寫法見
+     * `Plugin.configSchema`；`emit` 帶函式本體、不進中介表示，不得寫進宣告。
+     */
+    readonly configSchema?: unknown;
+}
+/** 第三方套件用本函式建構 target。 */
+export declare function defineTarget(platform: string, emit: AdapterEmit, options?: {
+    readonly configSchema?: unknown;
+}): AdapterTarget;
+/**
+ * 格式化為人讀文字：委派核心 `adapter::Report::format`（經
+ * `promptex-js-binding` 的 `formatReport` 匯出，ADR-008），不在 SDK 側重寫。
+ *
+ * 這裡原本是一份 TypeScript 對等實作。它與核心那份已經分岔：核心會印強制力
+ * 階梯（`，強制力 {from} → {to}`），SDK 這份沒有，因為當時的 `DegradeItem`
+ * 連 `from`／`to` 兩個欄位都沒有。改為委派之後，第三方適配與內建平台的報告
+ * 是同一份機器碼產出的，不再有「寫的當下對得上、核心改了才分岔」的缺口。
+ */
+export declare function formatReport(report: EmitReport): string;
+/**
+ * 建立一份 `AdapterContext` 供命令列呼叫第三方 `emit` 或 `extend` 函式。
+ *
+ * 收平台名與配置單元的 `select`，兩者一起決定 `entries` 回傳哪些節點
+ * （見 `registry.ts` 的 `entriesFor`）：節點過濾在內建平台由核心的投影承擔
+ * （`meta.targets` 走 `adapter::is_distributed_to`、`select` 走 `toIR`），
+ * 第三方適配不經核心投影，同樣兩道排除因此必須在建構脈絡時就帶進來。
+ * 少了它們，宣告 `targets: ['claude']` 的節點會被第三方適配照樣產出，多個
+ * 配置單元共用同一個 `srcDir` 時每個落點還會收到全庫節點。
+ *
+ * 累積的落差經 `ctx.report(platform, emitted)` 取出，不再回傳兩個裸陣列：
+ * 裸陣列讓呼叫端能繞過介面直接組裝報告，作者的 `emit` 實作卻拿不到同一條
+ * 路徑，Python／Rust 兩側則是兩者都走 `report()`。同一件事在三個生態有兩種
+ * 形態，就是「這個生態的第三方適配做得到的事比另兩個少」。
+ */
+export declare function createAdapterContext(platform: string, select?: SelectSpec): AdapterContext;

package/dist/adapter.js

@@ -0,0 +1,127 @@
+// 第三方 adapter 的公開介面（AC-097 至 AC-101，platform-adaptation BC 的
+// 適配可擴充性）：官方（claude／codex）與第三方適配使用同一組
+// `AdapterContext` 方法，不存在「內建能用而擴充不能用」的私有 API。
+//
+// 兩條 adapter 路徑分工不同軸：內建平台的實際投影住 Rust core
+// （crates/promptex-core/src/adapter），以核心語言隨二進位分發；第三方
+// 適配住這裡（SDK 層），以作者選用的語言撰寫（本 SDK 為 TypeScript），
+// 不需要修改核心程式碼即可分發（AC-099）：command-line 工具
+// （src/cli/main.ts）偵測到 target 帶有 `emit` 時改呼叫這裡的函式，不
+// 透過核心二進位。第三方適配因此綁語言：以 TypeScript 實作者只服務
+// TypeScript 專案，這是擴充自由度的顯性代價（AC-101）。
+//
+// 渲染（`render`）接受落點表而非回呼函式（AC-100）：算 `[名稱](相對路徑)`
+// 需要同時知道引用方與目標各在哪，若介面設計成接受回呼，跨語言邊界就得
+// 傳函式指標；改為接受落點表後只有資料進出。渲染邏輯本身（`Piece[]` →
+// markdown 字串，含 `ref` 解析與相對路徑計算）委派 Rust core 的
+// `crates/promptex-core/src/project/mod.rs`（`render_pieces`／`render_ref`／
+// `relative_path`，經 `promptex-js-binding` 的 `renderPieces` 匯出，ADR-008）：
+// 本檔只做「求值期概念（`Content`，含函式呼叫、引用建構子）轉成純資料
+// `Piece[]`」這一步，那一步依賴 SDK 側的註冊表（`engine`），核心無從得知；
+// 轉換完成後的渲染是同一份機器碼，不再有第二份 TypeScript 對等實作要與
+// 核心人工核對是否同步。
+import { contentToPieces, engine, entriesFor } from './registry.js';
+import { currentLocale } from './i18n.js';
+import { loadNativeCore } from './native.js';
+/** 第三方套件用本函式建構 target。 */
+export function defineTarget(platform, emit, options = {}) {
+    return {
+        platform,
+        emit,
+        ...(options.configSchema !== undefined ? { configSchema: options.configSchema } : {}),
+    };
+}
+/**
+ * 格式化為人讀文字：委派核心 `adapter::Report::format`（經
+ * `promptex-js-binding` 的 `formatReport` 匯出，ADR-008），不在 SDK 側重寫。
+ *
+ * 這裡原本是一份 TypeScript 對等實作。它與核心那份已經分岔：核心會印強制力
+ * 階梯（`，強制力 {from} → {to}`），SDK 這份沒有，因為當時的 `DegradeItem`
+ * 連 `from`／`to` 兩個欄位都沒有。改為委派之後，第三方適配與內建平台的報告
+ * 是同一份機器碼產出的，不再有「寫的當下對得上、核心改了才分岔」的缺口。
+ */
+export function formatReport(report) {
+    return loadNativeCore().formatReport(JSON.stringify(report), currentLocale());
+}
+/**
+ * 建立一份 `AdapterContext` 供命令列呼叫第三方 `emit` 或 `extend` 函式。
+ *
+ * 收平台名與配置單元的 `select`，兩者一起決定 `entries` 回傳哪些節點
+ * （見 `registry.ts` 的 `entriesFor`）：節點過濾在內建平台由核心的投影承擔
+ * （`meta.targets` 走 `adapter::is_distributed_to`、`select` 走 `toIR`），
+ * 第三方適配不經核心投影，同樣兩道排除因此必須在建構脈絡時就帶進來。
+ * 少了它們，宣告 `targets: ['claude']` 的節點會被第三方適配照樣產出，多個
+ * 配置單元共用同一個 `srcDir` 時每個落點還會收到全庫節點。
+ *
+ * 累積的落差經 `ctx.report(platform, emitted)` 取出，不再回傳兩個裸陣列：
+ * 裸陣列讓呼叫端能繞過介面直接組裝報告，作者的 `emit` 實作卻拿不到同一條
+ * 路徑，Python／Rust 兩側則是兩者都走 `report()`。同一件事在三個生態有兩種
+ * 形態，就是「這個生態的第三方適配做得到的事比另兩個少」。
+ */
+export function createAdapterContext(platform, select) {
+    const degraded = [];
+    const unsupported = [];
+    return {
+        entries: (kind) => entriesFor(platform, select, kind),
+        render: (entry, selfPath, layout) => renderEntry(entry, selfPath, layout),
+        overrides: (entry) => nonEmpty(resolveOverrides(entry, platform).native),
+        reserved: (entry) => nonEmpty(resolveOverrides(entry, platform).reserved),
+        unsupportedOverride: (entry, form) => {
+            const nodeJson = JSON.stringify(overridePayload(entry));
+            const item = JSON.parse(loadNativeCore().unsupportedOverride(nodeJson, platform, form, currentLocale()));
+            if (item)
+                unsupported.push(item);
+        },
+        degrade: (item) => degraded.push(item),
+        unsupported: (item) => unsupported.push(item),
+        report: (platform, emitted) => ({ platform, emitted: [...emitted], degraded: [...degraded], unsupported: [...unsupported] }),
+        hasNotes: () => degraded.length > 0 || unsupported.length > 0,
+    };
+}
+// ── 覆寫讀取：委派核心 adapter::resolve_overrides（ADR-004），SDK 不自行解析 ──
+/**
+ * 交給核心的節點形態：只要 `kind`／`id`／`config` 三欄。
+ *
+ * 不序列化整個節點：`name` 與 `content` 與覆寫無關，而 `content` 在求值期
+ * 含函式呼叫與引用建構子，要求它先轉成 `Piece[]` 才讀得到覆寫，等於為了讀
+ * 幾個鍵付一次完整的內容正規化。
+ */
+function overridePayload(entry) {
+    return { kind: entry.kind, id: entry.id, config: entry.def.config ?? null };
+}
+/** 委派核心把覆寫拆成平台原生鍵與框架保留鍵兩份。 */
+function resolveOverrides(entry, platform) {
+    const nodeJson = JSON.stringify(overridePayload(entry));
+    return JSON.parse(loadNativeCore().platformOverrides(nodeJson, platform, currentLocale()));
+}
+/** 空物件與未宣告在介面上是同一件事（ADR-004），一律回 `undefined`。 */
+function nonEmpty(map) {
+    return Object.keys(map).length > 0 ? map : undefined;
+}
+// ── 渲染：委派核心 project::render_pieces（AC-100），SDK 不再重複實作 ──
+/**
+ * `Content` → `Piece[]` 這一步留在 SDK（依賴 `entry.def.content` 與求值期
+ * 概念，核心無從得知），轉換完成後把純資料連同落點表、名稱表一併交給
+ * 原生綁定的 `renderPieces`，回傳的字串就是最終 markdown。
+ *
+ * 名稱表覆蓋 `engine.entries()` 當下的全部節點（依 `kind:id` 複合鍵，與核心
+ * `key()` 同構）：渲染發生在單次呼叫裡，無法像原本的 TypeScript 實作那樣
+ * 在遇到 `ref` 當下才惰性查一次，因此在呼叫前把可能用得到的名稱全部帶過去。
+ */
+function renderEntry(entry, selfPath, layout) {
+    const pieces = contentToPieces(entry.def.content);
+    const layoutObj = {};
+    for (const [k, v] of layout)
+        layoutObj[k] = v;
+    const namesObj = {};
+    for (const e of engine.entries())
+        namesObj[`${e.kind}:${e.id}`] = e.name;
+    // 逐個引數先接成綁定那側的參數名再傳，讓位置引數的對應關係在源碼上看得出
+    // 來；三方的參數順序目前沒有自動對拍。
+    // 內文從第幾級標題起算不在這裡給：三個 SDK 的 `ctx.render` 必須渲染出逐字
+    // 相同的 markdown，該值住核心（`ops::THIRD_PARTY_BODY_DEPTH`）。
+    const piecesJson = JSON.stringify(pieces);
+    const layoutJson = JSON.stringify(layoutObj);
+    const namesJson = JSON.stringify(namesObj);
+    return loadNativeCore().renderPieces(piecesJson, selfPath, layoutJson, namesJson, currentLocale());
+}